
\section{Markers, Linestyles, (Background) Colors and Colormaps}
\label{sec:markers}

The following options of \Tikz{} are available to plots.


\subsection{Markers}

This list is copied from~\cite[Section~29]{tikz}:
%
\pgfmanualpdflabel{/tikz/mark}{}%
\begingroup
\newenvironment{longdescription}[0]{%
    \begin{list}{}{%
        \leftmargin=4.7cm
        \setlength{\labelwidth}{4.7cm}%
        \renewcommand{\makelabel}[1]{\hfill\textbf{\texttt{##1}}}%
    }%
}{%
    \end{list}%
}%
\def\showit#1{%
    \tikz\draw [
        gray,
        thin,
        mark options={fill=yellow!80!black,draw=black,scale=2},
        x=0.8cm,y=0.3cm,
        #1,
    ] plot coordinates {(0,0) (1,1) (2,0) (3,1)};%
}%
\def\showitpgfplots#1{%
\begin{tikzpicture}[baseline]
    \begin{axis}[
        anchor=north,
        xticklabels=,
        yticklabels=,
        zticklabels=,
        width=5cm,
    ]
        \addplot3 [
            gray,
            thin,
            mark options={
                scale=2,
                fill=yellow!80!black,
                draw=black,
            },
            #1,
        ] coordinates {(0,0,0) (0.3,0.6,0.3) (2,0,0.1) (2.3,1,0.2)};
    \end{axis}
\end{tikzpicture}%
}%
\begin{longdescription}
    \item[mark=*] \showit{mark=*}
    \item[mark=x] \showit{mark=x}
    \item[mark=+] \showit{mark=+}
%    \item[mark=ball] \showit{mark=ball}
\end{longdescription}
%
And with |\usetikzlibrary{plotmarks}|:
%
\begin{longdescription}
    \item[mark=$-$] \showit{mark=-}
    \item[mark=$\vert$] \showit{mark=|}
    \item[mark=o] \showit{mark=o}
    \item[mark=asterisk] \showit{mark=asterisk}
    \item[mark=star] \showit{mark=star}
    \item[mark=10-pointed star] \showit{mark=10-pointed star}
    \item[mark=oplus] \showit{mark=oplus}
    \item[mark=oplus*] \showit{mark=oplus*}
    \item[mark=otimes] \showit{mark=otimes}
    \item[mark=otimes*] \showit{mark=otimes*}
    \item[mark=square] \showit{mark=square}
    \item[mark=square*] \showit{mark=square*}
    \item[mark=triangle] \showit{mark=triangle}
    \item[mark=triangle*] \showit{mark=triangle*}
    \item[mark=diamond] \showit{mark=diamond}
    \item[mark=diamond*] \showit{mark=diamond*}
    \item[mark=halfdiamond*] \showit{mark=halfdiamond*}
    \item[mark=halfsquare*] \showit{mark=halfsquare*}
    \item[mark=halfsquare right*] \showit{mark=halfsquare right*}
    \item[mark=halfsquare left*] \showit{mark=halfsquare left*}
    \item[mark=Mercedes star] \showit{mark=Mercedes star}
    \item[mark=Mercedes star flipped] \showit{mark=Mercedes star flipped}
    \item[mark=halfcircle] \showit{mark=halfcircle}

        One half is filled with white (more precisely, with |mark color|).

    \item[mark=halfcircle*] \showit{mark=halfcircle*}

        One half is filled with white (more precisely, with |mark color|) and
        the other half is filled with the actual |fill| color.

    \item[mark=pentagon] \showit{mark=pentagon}
    \item[mark=pentagon*] \showit{mark=pentagon*}
    \item[mark=ball] \showit{mark=ball,mark options={ball color=yellow!80!black,scale=2}}

        This marker is special and can easily generate big output files if
        there are lots of them. It is also special in that it needs
        |ball color| to be set (in our case, it is |ball color=yellow!80!black|.

    \item[mark=text] \showit{mark=text,every mark/.append style={scale=0.5}}

        This marker is special as it can be configured freely. The character
        (or even text) used is configured by a set of variables, see below.

    \item[mark=cube] \showitpgfplots{mark=cube}

        This marker is only available inside of a \PGFPlots{} axis, it draws a
        cube with axis parallel faces. Its dimensions can be configured
        separately, see below.

    \item[mark=cube*] \showitpgfplots{mark=cube*}
    \item[User defined] It is possible to define new markers with
        |\pgfdeclareplotmark|, see below.
\end{longdescription}
%
All these options have been drawn with the additional options
%
\begin{codeexample}[code only]
\draw [
    gray,
    thin,
    mark options={
        scale=2,fill=yellow!80!black,draw=black,
    },
]
\end{codeexample}
%
Please see Section~\ref{sec:colors} for how to change |draw| and |fill| colors.
Note that each of the provided marks can be rotated freely by means of
|mark options={rotate=90}| or |every mark/.append style={rotate=90}|.

\begin{key}{/tikz/mark size=\marg{dimension} (initially 2pt)}
    This \Tikz{} option allows to set marker sizes to \meta{dimension}. For
    circular markers, \meta{dimension} is the radius, for other plot marks it
    is about half the width and height.
\end{key}

\begin{pgfplotsxykey}{cube/size \x=\marg{dimension} (initially |\textbackslash pgfplotmarksize|=2pt)}
    Sets the size for |mark=cube| separately for every axis.
\end{pgfplotsxykey}

\begin{key}{/tikz/every mark}
    This \Tikz{} style can be reconfigured to set marker appearance options
    like colors or transformations like scaling or rotation. \PGFPlots{}
    appends its |cycle list| options to this style.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=2cm]
    \addplot coordinates
        {(-2,0) (-1,1) (0,0) (1,1) (2,0)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\tikzset{every mark/.append style={scale=2}}
\begin{tikzpicture}
\begin{axis}[y=2cm]
    \addplot coordinates
        {(-2,0) (-1,1) (0,0) (1,1) (2,0)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=2cm]
  \addplot+ [
    mark=halfcircle*,
    every mark/.append style={rotate=90}]
  coordinates
    {(-2,0) (-1,1) (0,0) (1,1) (2,0)};

  \addplot+ [
    mark=halfcircle*,
    every mark/.append style={rotate=180}]
  coordinates
    {(-2,-0.1) (-1,0.9) (0,-0.1) (1,0.9) (2,-0.1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    Note that |every mark| is kind of static in the sense that it is evaluated
    once only. If you need individually colored marks as part of a |scatter|
    plot, you will need to resort to |scatter/use mapped color|.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=2cm]
    \addplot+ [
        mark=ball,
        mark size=4pt,
        scatter,% enable scatter
        scatter src=rand,% the "color data"
        % configure individual appearances:
        scatter/use mapped color=
            {ball color=mapped color}]
    coordinates
        {(-2,0) (-1,1) (0,0) (1,1) (2,0)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{key}

\begin{stylekey}{/pgfplots/no markers}
    A key which overrides any |mark| value set by |cycle list| of option lists
    after |\addplot|.

    If this style is provided as argument to a complete axis, it is appended to
    |every axis plot post| such that it disables markers even for |cycle list|s
    which contain markers.
\end{stylekey}

\begin{key}{/tikz/mark repeat=\marg{integer} (initially empty)}
    Allows to draw only each $n$th |mark| where $n$ is provided as
    \meta{integer}.
\end{key}

\begin{key}{/tikz/mark phase=\marg{integer $p$} (initially 1)}
    This option allows to control which markers are drawn. It is primarily used
    together with the \Tikz{} option |mark repeat=|$r$: it tells \tikzname{}
    that the first mark to be drawn should be the $p$th, followed by the $(p +
    r)$th, then the $(p + 2r)$th, and so on.
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[tiny]
        \addplot+ [scatter] {sin(deg(x))};
    \end{axis}
\end{tikzpicture}
\begin{tikzpicture}
    \begin{axis}[tiny]
        \addplot+ [scatter,
            mark repeat=3,mark phase=2]
                {sin(deg(x))};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    Here, $p=1$ is the first point (the one with |\coordindex|$=0$).
\end{key}

\begin{key}{/tikz/mark indices=\marg{index list} (initially empty)}
    Allows to draw only the marker whose index numbers are in the argument
    list.
\end{key}

\begin{key}{/pgf/mark color=\marg{color} (initially empty)}
    Defines the \emph{additional} fill color for the |halfcircle|,
    |halfcircle*|, |halfdiamond*| and |halfsquare*| markers. An empty value
    uses |white| (which is the initial configuration). The value |none|
    disables filling for this part.

    These markers have two distinct fill colors, one is determined by |fill| as
    for any other marker and the other one is |mark color|.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=2cm]
    \addplot [
        blue,
        mark color=blue!50!white,
        mark=halfcircle*
    ] coordinates {
        (-2,0) (-1,1) (0,0) (1,1) (2,0)
    };
    \addplot [
        red,
        mark color=red!50!white,
        mark=halfsquare*,
    ] coordinates {
        (-2,-0.1) (-1,0.9) (0,-0.1) (1,0.9) (2,-0.1)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}

    Note that this key requires \PGF{} 2.10 or later.
\end{key}

\begin{key}{/tikz/mark options=\marg{options}}
    Resets |every mark| to \marg{options}.
\end{key}

\begin{key}{/pgf/text mark=\marg{text} (initially p)}
    Changes the text shown by |mark=text|.

    With |/pgf/text mark=m|: \pgfkeys{/pgf/text mark=m}\showit{mark=text,every
    mark/.append style={scale=0.5}}

    With |/pgf/text mark=A|: \pgfkeys{/pgf/text mark=A}\showit{mark=text,every
    mark/.append style={scale=0.5}}

    There is no limitation about the number of characters or whatever. In fact,
    any \TeX{} material can be inserted as \meta{text}, including images.
\end{key}

\begin{key}{/pgf/text mark style=\marg{options for \texttt{mark=text}}}
    Defines a set of options which control the appearance of |mark=text|.

    If |/pgf/text mark as node=false| (the default), \meta{options} is provided
    as argument to |\pgftext| -- which provides only some basic keys like
    |left|, |right|, |top|, |bottom|, |base| and |rotate|.

    If |/pgf/text mark as node=true|, \meta{options} is provided as argument to
    |\node|. This means you can provide a very powerful set of options
    including |anchor|, |scale|, |fill|, |draw|, |rounded corners|, etc.
\end{key}

\begin{key}{/pgf/text mark as node=\mchoice{true,false} (initially false)}
    Configures how |mark=text| will be drawn: either as |\node| or as
    |\pgftext|.

    The first choice is highly flexible and possibly slow, the second is very
    fast and usually enough.
\end{key}

\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}}
    Defines a new marker named \meta{plot mark name}. Whenever it is used,
    \meta{code} will be invoked. It is supposed to contain (preferable \PGF{}
    basic level) drawing commands. During \meta{code}, the coordinate system's
    origin denotes the coordinate where the marker shall be placed.

    Please refer to~\cite{tikz} section ``Mark Plot Handler'' for more detailed
    information.
\end{command}

\begin{stylekey}{/pgfplots/every axis plot post (initially {})}
    The
    %\todosp{shall the curly brackets after ``initially'' be shown? Also
    %this style is again defined in Section~4.18.1 (see corresponding index
    %entry). Is that intended?}
    % The replication makes sense imho, but the curly braces appear to
    % be a tech debt of the manual styles
    |every axis plot post| style can be used to overwrite parts (or all) of
    the drawing styles which are assigned for plots.
    %
\begin{codeexample}[]
% Overwrite any cycle list:
\pgfplotsset{
    every axis plot post/.append style={
        mark=triangle,
        every mark/.append style={rotate=90},
    },
}
\begin{tikzpicture}
    \begin{axis}[y=2cm]
        \addplot coordinates {
            (-2,0) (-1,1) (0,0) (1,1) (2,0)
        };
    \end{axis}
\end{tikzpicture}
\end{codeexample}
\end{stylekey}

Markers paths are not subjected to clipping as other parts of the figure.
Markers are either drawn completely or not at all.

\Tikz{} offers more options for marker fine tuning, please refer to~\cite{tikz}
for details.


\subsection{Line Styles}

\def\showit#1{%
    \tikz\draw[
        black,
        x=0.8cm,y=0.3cm,
        #1]
    plot coordinates {(0,0) (1,1) (2,0) (3,1)};
}%
%
The following line styles are predefined in \Tikz{}.
%
\begin{stylekey}{/tikz/solid}
    \showit{style=solid}
\end{stylekey}

\begin{stylekey}{/tikz/dotted}
    \showit{style=dotted}
\end{stylekey}

\begin{stylekey}{/tikz/densely dotted}
    \showit{style=densely dotted}
\end{stylekey}

\begin{stylekey}{/tikz/loosely dotted}
    \showit{style=loosely dotted}
\end{stylekey}

\begin{stylekey}{/tikz/dashed}
    \showit{style=dashed}
\end{stylekey}

\begin{stylekey}{/tikz/densely dashed}
    \showit{style=densely dashed}
\end{stylekey}

\begin{stylekey}{/tikz/loosely dashed}
    \showit{style=loosely dashed}
\end{stylekey}

\begin{stylekey}{/tikz/dashdotted}
    \showit{style=dashdotted}
\end{stylekey}

\begin{stylekey}{/tikz/densely dashdotted}
    \showit{style=densely dashdotted}
\end{stylekey}

\begin{stylekey}{/tikz/loosely dashdotted}
    \showit{style=loosely dashdotted}
\end{stylekey}

\begin{stylekey}{/tikz/dashdotdotted}
    \showit{style=dashdotdotted}
\end{stylekey}

\begin{stylekey}{/tikz/densely dashdotdotted}
    \showit{style=densely dashdotdotted}
\end{stylekey}

\begin{stylekey}{/tikz/loosely dashdotdotted}
    \showit{style=loosely dashdotdotted}
\end{stylekey}
%
\noindent since these styles apply to markers as well, you may want to consider
using
%
\begin{codeexample}[code only]
\pgfplotsset{
    every mark/.append style={solid},
}
\end{codeexample}
%
\noindent in marker styles.

Besides linestyles, \PGF{} also offers (a lot of) arrow heads. Please refer
to~\cite{tikz} for details.
%
\endgroup


\subsection{Edges and Their Parameters}

When \PGFPlots{} connects points, it relies on \PGF{} drawing parameters to
create proper edges (and it only changes them in the |every patch| style).

It might occasionally be necessary to change these parameters:

\begin{keylist}{
    /tikz/line cap=\mchoice{round,rect,butt} (initially butt),
    /tikz/line join=\mchoice{round,bevel,miter} (initially miter),
    /tikz/miter limit=\meta{factor} (initially 10)%
}
    These keys control how lines are joined at edges. Their description is
    beyond the scope of this manual, so interested readers should
    consult~\cite{tikz}.

    Here is just an example illustrating why it might be of interest to study
    these parameters:
% \usetikzlibrary{spy}
\begin{codeexample}[]
% requires \usetikzlibrary{spy}
\begin{tikzpicture}[spy using outlines=
    {circle, magnification=6, connect spies}]
\begin{axis}[no markers,grid=major,
    every axis plot post/.append style={thick}]
\addplot  coordinates
 {(0, 0) (0, 0.9) (1, 0.9) (2, 1) (3, 0.9) (80, 0)};
\addplot+ [line join=round] coordinates
 {(0, 0) (0, 0.9) (2, 0.9) (3, 1) (4, 0.9) (80, 0)};
\addplot+ [line join=bevel] coordinates
 {(0, 0) (0, 0.9) (3, 0.9) (4, 1) (5, 0.9) (80, 0)};
\addplot+ [miter limit=5] coordinates
 {(0, 0) (0, 0.9) (4, 0.9) (5, 1) (6, 0.9) (80, 0)};

    \coordinate (spypoint)     at (3,1);
    \coordinate (magnifyglass) at (60,0.7);
\end{axis}

\spy [blue, size=2.5cm] on (spypoint)
    in node[fill=white] at (magnifyglass);
\end{tikzpicture}
\end{codeexample}
\end{keylist}


\subsection{Font Size and Line Width}

Often, one wants to change line width and font sizes for plots. This can be
done using the following options of \Tikz{}.

\begin{key}{/tikz/font=\marg{font name} (initially \textbackslash normalfont)}
    Sets the font which is to be used for text in nodes (like tick labels,
    legends or descriptions).

    A font can be any \LaTeX{} argument like |\footnotesize| or
    |\small\bfseries|.\footnote{Con\TeX{}t and plain \TeX{} users need to provide
    other statements, of course.}

    It may be useful to change fonts only for specific axis descriptions, for
    example using
\begin{codeexample}[code only]
\pgfplotsset{
    tick label style={font=\small},
    label style={font=\small},
    legend style={font=\footnotesize},
}
\end{codeexample}

    See also the predefined styles |normalsize|, |small| and |footnotesize| in
    Section~\ref{sec:scaling:styles}.
\end{key}

\begin{key}{/tikz/line width=\marg{dimension} (initially 0.4pt)}
    Sets the line width. Please note that line widths for tick lines and grid
    lines are predefined, so it may be necessary to override the styles
    |every tick| and |every axis grid|.

    The |line width| key is changed quite often in \Tikz{}. You should use
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={line width=1pt}}
\end{codeexample}
    %
    or
    %
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={thick}}
\end{codeexample}
    %
    to change the overall line width. To also adjust ticks and grid lines, one
    can use
    %
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={
    line width=1pt,
    tick style={line width=0.6pt}}}
\end{codeexample}
    %
    or styles like
    %
\begin{codeexample}[code only]
\pgfplotsset{every axis/.append style={
    thick,
    tick style={semithick}}}
\end{codeexample}
    %
    The `|every axis plot|' style can be used to change line widths for plots
    only.
\end{key}

\begin{keylist}[/tikz]{thin,ultra thin,very thin,semithick,thick,very thick,ultra thick}
    These \Tikz{} styles provide different predefined line widths.
\end{keylist}

\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
    font=\large,
    line width=1pt,
    tick style={line width=0.8pt}}}
\begin{tikzpicture}
\begin{loglogaxis}[
    legend pos=south west,
    xlabel=\textsc{Dof},
    ylabel=$L_2$ Error
]
\addplot coordinates {
    (5,8.312e-02)    (17,2.547e-02)   (49,7.407e-03)
    (129,2.102e-03)  (321,5.874e-04)  (769,1.623e-04)
    (1793,4.442e-05) (4097,1.207e-05) (9217,3.261e-06)
};

\addplot coordinates{
    (7,8.472e-02)    (31,3.044e-02)   (111,1.022e-02)
    (351,3.303e-03)  (1023,1.039e-03) (2815,3.196e-04)
    (7423,9.658e-05) (18943,2.873e-05)
    (47103,8.437e-06)};

\addplot coordinates{
    (9,7.881e-02)     (49,3.243e-02)   (209,1.232e-02)
    (769,4.454e-03)   (2561,1.551e-03)
    (7937,5.236e-04)  (23297,1.723e-04)
    (65537,5.545e-05) (178177,1.751e-05)};

\addplot coordinates{
    (11,6.887e-02)    (71,3.177e-02)   (351,1.341e-02)
    (1471,5.334e-03)  (5503,2.027e-03)
    (18943,7.415e-04) (61183,2.628e-04)
    (187903,9.063e-05) (553983,3.053e-05)};

\addplot coordinates{
    (13,5.755e-02)    (97,2.925e-02)   (545,1.351e-02)
    (2561,5.842e-03)  (10625,2.397e-03)
    (40193,9.414e-04) (141569,3.564e-04)
    (471041,1.308e-04) (1496065,4.670e-05)};
\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
%
The preceding example defines data which is used a couple of times throughout
this manual; it is referenced by
\label{page:plotcoords:src}%
\declareandlabel{\plotcoords}.%

\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
    font=\footnotesize,
    thin,
    tick style={ultra thin}},
}
\begin{tikzpicture}
    \begin{loglogaxis}[
        xlabel=\textsc{Dof},
        ylabel=$L_2$ Error
    ]
        % see above for this macro:
        \plotcoords
        \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
    \end{loglogaxis}
\end{tikzpicture}
\end{codeexample}


\subsection{Colors}
\label{sec:colors}

{
\def\showcolorandname#1{%
    \showcolor{#1}~\texttt{\pgfmanualpdflabel{#1}{#1}}%
}
\def\showcolor#1{%
    \tikz \draw[black,fill={#1}] (0,0) rectangle (1em,0.6em);%
}

\PGF{} uses the color support of |xcolor|. Therefore, the main reference for
how to specify colors is the |xcolor| manual~\cite{xcolor}. The \PGF{}
manual~\cite{tikz} is the reference for how to select colors for specific
purposes like drawing, filling, shading, patterns etc. This section contains a
short overview over the specification of colors in~\cite{xcolor} (which is not
limited to \PGFPlots{}).

The package |xcolor| defines a set of predefined colors, namely
%
\showcolorandname{red},
\showcolorandname{green},
\showcolorandname{blue},
\showcolorandname{cyan},
\showcolorandname{magenta},
\showcolorandname{yellow},
\showcolorandname{black},
\showcolorandname{gray},
\showcolorandname{white},
\showcolorandname{darkgray},
\showcolorandname{lightgray},
\showcolorandname{brown},
\showcolorandname{lime},
\showcolorandname{olive},
\showcolorandname{orange},
\showcolorandname{pink},
\showcolorandname{purple},
\showcolorandname{teal},
\showcolorandname{violet}.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[enlarge x limits=false]
    \addplot [red,samples=500] {sin(deg(x))};
    \addplot [orange,samples=7] {sin(deg(x))};
    \addplot [teal,const plot,samples=14]
        {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

Besides predefined colors, it is possible to \emph{mix} two (or more) colors.
For example, \showcolorandname{red!30!white} contains $30\%$ of
\showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently,
one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$
white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This
mixing can be done with any color, for example \showcolorandname{red!50!green},
\showcolorandname{blue!50!yellow} or \showcolorandname{green!60!black}.

A different type of color mixing is supported, which allows to take $100\%$ of
\emph{each} component. For example, \showcolorandname{rgb,2:red,1;green,1} will
add $1/2$ part \showcolorandname{red} and $1/2$ part \showcolorandname{green}
and we reproduced the example from above. Using the denominator~$1$ instead
of~$2$ leads to \showcolorandname{rgb,1:red,1;green,1} which uses $1$ part
\showcolorandname{red} and $1$ part \showcolorandname{green}. Many programs
allow to select pieces between $0,\dotsc,255$, so a denominator of $255$ is
useful. Consequently, \showcolorandname{rgb,255:red,231;green,84;blue,121} uses
$231/255$ red, $84/255$ green and $121/255$. This corresponds to the standard
RGB color $(231,84,121)$. Other examples are
\showcolorandname{rgb,255:red,32;green,127;blue,43},
\showcolorandname{rgb,255:red,178;green,127;blue,43},
\showcolorandname{rgb,255:red,169;green,178;blue,43}.

It is also possible to use RGB values, the HSV color model, the CMY (or CMYK)
models, or the HTML color syntax directly. However, this requires some more
programming. I suppose this is the fastest (and probably the most
uncomfortable) method to use colors. For example,
%
\begin{codeexample}[]
\definecolor{color1}{rgb}{1,1,0}
\tikz \fill[color1]
    (0,0) rectangle (1em,0.6em);
\end{codeexample}
%
\noindent creates the color with $100\%$ \showcolorandname{red}, $100\%$
\showcolorandname{green} and $0\%$ \showcolorandname{blue};
%
\begin{codeexample}[]
\definecolor{color1}{cmyk}{0.6,0.9,0.5,0.1}
\tikz \fill[color1]
    (0,0) rectangle (1em,0.6em);
\end{codeexample}
%
\noindent creates the color with $60\%$ \showcolorandname{cyan}, $90\%$
\showcolorandname{magenta}, $50\%$ \showcolorandname{yellow} and $10\%$
\showcolorandname{black};

\begin{codeexample}[]
\definecolor{color1}{HTML}{D0B22B}
\tikz \fill[color1]
    (0,0) rectangle (1em,0.6em);
\end{codeexample}
%
\noindent creates the color with $208/255$ pieces red, $178/255$ pieces green
and $43$ pieces blue, specified in standard HTML notation. Please refer to the
|xcolor| manual~\cite{xcolor} for more details and color models.

The |xcolor| package provides even more methods to combine colors, among them
the prefix `|-|' (minus) which changes the color into its complementary color
(\showcolorandname{-black}, \showcolorandname{-white}, \showcolorandname{-red})
or color wheel calculations. Please refer to the |xcolor| manual~\cite{xcolor}.
}%

\begin{keylist}{
    /tikz/color=\marg{a color},
    /tikz/draw=\marg{stroke color},
    /tikz/fill=\marg{fill color}%
}
    These keys are (generally) used to set colors. Use |color| to set the color
    for both drawing and filling. Instead of |color=|\marg{color name} you can
    simply write \meta{color name}. The |draw| and |fill| keys only set colors
    for stroking and filling, respectively.

    Use |draw=none| to disable drawing and |fill=none| to disable
    filling.\footnote{Up to now, plot marks always have a stroke color (some
    also have a fill color). This restriction may be lifted in upcoming
    versions.}
%    This does also work for markers.
%--------------------------------------------------
%\ begin{codeexample}[]
%\begin{tikzpicture}
%\begin{axis}
%    \addplot+[only marks,mark=square*,
%        mark options={fill=red!50!white,draw=none}]
%        {4*x^2 - 2*x +4 };
%\end{axis}
%\end{tikzpicture}
%\end{codeexample}
%--------------------------------------------------

    Since these keys belong to \Tikz{}, the complete documentation can be found
    in the \Tikz{} manual~\cite[Section ``Specifying a Color'']{tikz}.
\end{keylist}


\subsubsection{Color Spaces}

Since \PGFPlots{} relies on |xcolor|, all mechanisms of |xcolor| to define
color spaces apply here as well.

One of the most useful approaches is global color space conversion: if you want
a document which contains only colors in the |cmyk| color spaces, you can say

\begin{codeexample}[code only]
\usepackage[cmyk]{xcolor}
\usepackage{pgfplots}
\end{codeexample}
%
\noindent in order to convert all colors of the entire document (including all
shaded) to |cmyk|.

The same can be achieved by means of the |xcolor| statement
\declareandlabel{\selectcolormodel}.
%
\begin{codeexample}[code only]
\selectcolormodel{cmyk}
\end{codeexample}


\subsection{Color Maps}

A ``color map'' is a sequence of colors with smooth transitions between them.
Color maps are often used to visualize ``color data'' in plots: in this case, a
plot has the position coordinates $(x,y)$ and some additional scalar value
(|point meta|) which can be used as ``color data''. The smallest encountered
|point meta| is then mapped to the first color of a |colormap|, the largest
encountered value of |point meta| is mapped to the last color of a |colormap|,
and interpolation happens in-between.

\label{pgfplots:colormap}
\begin{pgfplotskey}{colormap name=\marg{color map name} (initially hot)}
    Changes the current color map to the already defined map named \meta{color
    map name}. The predefined color maps are

    \begin{tabular}{>{\ttfamily}ll}
        viridis & \pgfplotsshowcolormap{viridis} \\
        hot     & \pgfplotsshowcolormap{hot}     \\
    \end{tabular}

    The definition can be found in the documentation for |colormap/hot| and
    |colormap/viridis|, respectively. These, and further color maps, are
    described below.

    Color maps can be used, for example, in |scatter| plots and |surf|ace
    plots.

    You can use |colormap| to create new color maps (see below).
\end{pgfplotskey}

\begin{pgfplotskey}{colormap=\marg{name}\marg{color specification}}
    Defines a new colormap named \meta{name} according to \meta{color
    specification} and activates it using |colormap name=|\marg{name}.

    A simple \meta{color specification} is just a sequence of color definitions
    of type

    \meta{color type}|=(|\meta{color value}|)|

    separated by either white spaces or semicolon or comma:
    %
\begin{codeexample}[code only]
\pgfplotsset{colormap={CM}{rgb=(0,0,1) color=(black) rgb255=(238,140,238)}}
\end{codeexample}
\pgfplotsshowcolormapexample{rgb=(0,0,1) color=(black) rgb255=(238,140,238)}

    Here, the three input colors form the left end, middle point, and right end
    of the interval, respectively. A couple of \meta{color type}s are
    available, the \meta{color value} depends on the actual \meta{color type}
    which is shown below in all detail. Most |colormap| definitions use the
    simple form and merely list suitable color definitions.

    A more advanced \meta{color specification} is one which defines both colors
    and positions in order to define the place of each color. In this case,
    \PGFPlots{} offers the syntax

    \meta{color type}|(|\meta{offset}|)=(|\meta{color value}|)|:

\begin{codeexample}[code only]
\pgfplotsset{colormap={CM}{rgb(-500)=(0,0,1) color(0)=(black) rgb255(1500)=(238,140,238)}}
\end{codeexample}
\pgfplotsshowcolormapexample{rgb(-500)=(0,0,1) color(0)=(black) rgb255(1500)=(238,140,238)}

    This syntax allows to distribute colors over the interval using nonuniform
    distances.


    \paragraph{Compatibility note:}

    \PGFPlots{} up to and including version $1.13$ offered just rudimentary
    support for nonuniform color maps. You need to write |compat=1.14| or
    higher in order to make use of nonuniform color maps.%
    \index{Color maps!Non uniform, compatibility constraints}

    The positions can be arbitrary numbers (or dimensions),\footnote{Note that
    \PGFPlots{} up to and including version $1.13$ only supported ranges
    $[0,16300]$.} but each new color must come with a larger position than its
    preceding one. The position can be omitted in which case it will be deduced
    from the context: if the first two colors have no position, the first will
    receive position~$0$ and the second will receive position ``$1\text{cm}$''.
    All following ones receive the last encountered mesh width. Note that
    nonuniform positions make a real difference in conjunction with
    |colormap access=piecewise const|.

    The precise input format is described in the following section.


    \subsubsection{Colormap Input Format Reference}
    \label{sec:colormap:input:format}

    Each entry in \meta{color specification} has the form

    \meta{color model}|(|\meta{position}|)=(|\meta{arguments}|)| or

    \meta{special mode}|(|\meta{position}|)=(|\meta{argument}| of |\meta{colormap name}|)|

    where the most common form is to specify a color using a \meta{color model}
    like |rgb=(0,0.5,1)|. The \meta{special mode}s are discussed later in
    Section~\ref{sec:pgfplots:colormaps:based:on:others} on
    page~\pageref{sec:pgfplots:colormaps:based:on:others}; they are useful to
    access colors of existing colormaps. The \meta{position} argument is
    optional and defaults to $0$ for the first color, $1\text{cm}$ for the
    second, and an automatically deduced mesh grid for all following ones. The
    number range of \meta{position} is arbitrary. Note that \PGFPlots{} merely
    remembers the relative distances of the \meta{positions}, not their
    absolute values. Consequently, a color map with positions $0,1,2$ is
    equivalent to one with $0,10,20$ or $-10,0,10$ or $-1100,-1000,-900$.
    \PGFPlots{} maps the input positions to the range $[0,1000]$ internally and
    works with these numbers. Each new color must have a \meta{position} which
    is larger than the preceding one.

    Available choices for \meta{color model} are
    %
    % ATTENTION : a VERY similar description (actually: the same) is in sec:surf:explicit:color
    % maintain both; the syntax is different
    \begin{description}
        \item \declareandlabel{rgb} which expects \meta{arguments} of the
            form |(|\meta{red}|,|\meta{green}|,|\meta{blue}|)| where each
            component is in the interval $[0,1]$,
        \item \declareandlabel{rgb255} which is similar to |rgb| except that
            each component is expected in the interval |[0,255]|,
        \item \declareandlabel{gray} in which case \meta{arguments} is a
            single number in the interval $[0,1]$,
        \item \declareandlabel{color} in which case \meta{arguments} contains
            a predefined (named) color like `|red|' or a color expression
            like `|red!50|',
        \item \declareandlabel{cmyk} which expects \meta{arguments} of the
            form
            |(|\meta{cyan}|,|\meta{magenta}|,|\meta{yellow}|,|\meta{black}|)|
            where each component is in the interval $[0,1]$,
        \item \declareandlabel{cmyk255} which is the same as |cmyk| but
            expects components in the interval $[0,255]$,
        \item \declareandlabel{cmy} which expects \meta{arguments} of the
            form |(|\meta{cyan}|,|\meta{magenta}|,|\meta{yellow}|)| where
            each component is in the interval $[0,1]$,
        \item \declareandlabel{hsb} which expects \meta{arguments} of the
            form |(|\meta{hue}|,|\meta{saturation}|,|\meta{brightness}|)|
            where each component is in the interval $[0,1]$,
        \item \declareandlabel{Hsb} which is the same as |hsb| except that
            \meta{hue} is accepted in the interval $[0,360]$ (degree),
        \item \declareandlabel{HTML} which is similar to |rgb255| except that
            each component is expected to be a hex number between |00| and
            |FF|,
        \item \declareandlabel{wave} which expects a single wave length as
            numeric argument in the range $[363,814]$.
    \end{description}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap={bw}{
        gray(0cm)=(0);
        gray(1cm)=(1);
    },
]
    \addplot+ [
        scatter,
        only marks,
        domain=0:8,
        samples=100,
    ] {exp(x)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    The choice of \meta{positions} influences the processing time: a uniform
    distance between the \meta{positions} allows more efficient lookup than
    nonuniform distances. If there is no visual difference and it does not hurt
    with respect to the number of data points, prefer color maps with uniform
    distances over nonuniform maps. Note that nonuniform maps make a huge
    difference in conjunction with |colormap access=piecewise constant|.
    \PGFPlots{} provides a simple way to map a nonuniform color definition to a
    uniform one: write the target mesh width as \emph{first item} in the
    specification. \PGFPlots{} will perform this interpolation automatically,
    provided all encountered \meta{positions} can be mapped to the target grid:
    \index{Color maps!Non uniform}

\begin{codeexample}[code only]
% non-uniform spacing example: the mesh width is provided as first
% part of the specification.
\pgfplotsset{colormap={violetnew}
    {[1cm] rgb255(0cm)=(25,25,122) color(1cm)=(white) rgb255(5cm)=(238,140,238)}}
\end{codeexample}
\pgfplotsshowcolormapexample{[1cm]
    rgb255(0cm)=(25,25,122)
    color(1cm)=(white)
    rgb255(5cm)=(238,140,238)
}

    \noindent In this last example, the mesh width has been provided explicitly
    and \PGFPlots{} interpolates the missing grid points on its own. It is an
    error if the provided positions are no multiple of the mesh width.


    \subsubsection{The Colorspace of a Colormap}

    \emph{Attention:} this section is essentially superfluous if you have
    configured the |xcolor| package to override color spaces globally (for
    example by means of |\usepackage[cmyk]{xcolor}| before loading \PGFPlots),
    see the end of this subsection.

    Even though a |colormap| accepts lots of color spaces on \emph{input} (in
    fact, it accepts most or all that |xcolor| provides), the \emph{output}
    color of a colorspace has strict limitations. The output colorspace is the
    one in which \PGFPlots{} interpolates between two other colors. To this
    end, it transforms input colors to the output color space. The output
    colorspace is also referred to as ``the colorspace of a colormap''.

    There are three supported color spaces for a |colormap|: the GRAY, RGB, and
    CMYK color spaces. Each access into a |colormap| requires linear
    interpolation which is performed in its color space. Color spaces make a
    difference: colors in different color spaces may be represented
    differently, depending on the output device. Many printers use CMYK for
    color printing, so providing CMYK colors might improve the printing quality
    on a color printer. The RGB color space is often used for display devices.
    The predefined |colormap|s in \PGFPlots{} all use RGB.

    Whenever a new |colormap| is created, \PGFPlots{} determines an associated
    color space. Then, each color in this specific |colormap| will be
    represented in its associated color space (converting colors automatically
    if necessary). Furthermore, every access into the |colormap| will be
    performed in its associated color space and every returned |mapped color|
    will be represented with respect to this color space. Furthermore, every
    shading generated by |shader=interp| will be represented with respect to
    the |colormap|'s associated color space.

    The color space is chosen as follows: in case
    |colormap default colorspace=auto| (the initial configuration), the color
    space depends on the \emph{first} encountered color in \meta{color
    specification}. For |rgb| or |gray| or |color|, the associated color space
    will be RGB (as it was in all earlier versions of \PGFPlots{}). For |cmyk|,
    the associated color space will be CMYK. If |colormap default colorspace|
    is either |gray|, |rgb| or |cmyk|, this specific color space is used and
    every color is converted automatically.

    \begin{pgfplotskey}{colormap default colorspace=\mchoice{auto,gray,rgb,cmyk} (initially auto)}
        Allows to set the color space of every \emph{newly created} |colormap|.
        The choices are explained in the previous paragraph.

        It is impossible to change the color space of an existing |colormap|;
        recreate it if conversion is required.

        The macro \declareandlabel{\pgfplotscolormapgetcolorspace}\marg{name}
        defines |\pgfplotsretval| to contain the color space of an existing
        |colormap name|, if you are in doubt.

        Note that this option has \emph{no effect} if you told |xcolor| to
        override the color space globally. More precisely, the use of
\begin{codeexample}[code only]
\usepackage[cmyk]{xcolor}
\end{codeexample}
        %
        or, alternatively,
        %
\begin{codeexample}[code only]
\selectcolormodel{cmyk}
\end{codeexample}
        %
        will cause all colors to be converted to |cmyk|, and \PGFPlots{} honors
        this configuration. Consequently, both these statements cause all
        colors to be interpolated in the desired color space, and all output
        colors will use this colorspace. This is typically exactly what you
        need.
    \end{pgfplotskey}


    \subsubsection{Predefined Colormaps}

    Available color maps are shown below.
\end{pgfplotskey}

\begin{stylekey}{/pgfplots/colormap/viridis}
    A style which installs the colormap ``viridis'' which has been defined by
    Stèfan van der Walt and Nathaniel Smith for |Matplotlib|. It is
    designated to be the default |colormap| for |Matplotlib| starting with
    version~2.0 and is released under the
    CC0\footnote{\url{https://creativecommons.org/about/cc0}}.

    The choice |viridis| is a downsampled copy included in \PGFPlots{}.

\begin{codeexample}[code only]
\pgfplotsset{
    colormap name=viridis,
}
\end{codeexample}
    \pgfplotsshowcolormap{viridis}

    This |colormap| has considerably better properties compared to other choices:
    %
    \begin{itemize}
        \item its color distribution is perceptually uniform (compare the
            definition in the link below),
        \item it is suitable for moderate forms of color blindness,
        \item it is still good when printed in black and white.
    \end{itemize}
    %
    Details about these properties can be found in
    \url{http://bids.github.io/colormap}.

    Please use the choice |colormap name=viridis| as this makes uses of the
    predefined colormap whereas |colormap/viridis| will redefine it.

    There is also a high resolution copy of |viridis| which is called
    |colormap/viridis high res| in the |colormaps| library. It resembles the
    original resolution of the authors, but it is visually almost identically
    to |viridis| and requires less resources in \TeX{}.
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/hot}
    A style which installs the colormap
    %
\begin{codeexample}[code only]
\pgfplotsset{
    colormap={hot}{color(0cm)=(blue); color(1cm)=(yellow); color(2cm)=(orange); color(3cm)=(red)}
}
\end{codeexample}

    \pgfplotsshowcolormap{hot}

    This is a pre-configured color map.
    %
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/hot2}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    /pgfplots/colormap={hot2}{[1cm]rgb255(0cm)=(0,0,0) rgb255(3cm)=(255,0,0)
        rgb255(6cm)=(255,255,0) rgb255(8cm)=(255,255,255)}
}
\end{codeexample}

    \pgfplotsshowcolormap{hot2}

    Note that this particular choice ships directly with \PGFPlots{}, you do not need to load the |colormaps| library for this value.

    \matlabcolormaptext
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/jet}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    /pgfplots/colormap={jet}{rgb255(0cm)=(0,0,128) rgb255(1cm)=(0,0,255)
        rgb255(3cm)=(0,255,255) rgb255(5cm)=(255,255,0) rgb255(7cm)=(255,0,0) rgb255(8cm)=(128,0,0)}
}
\end{codeexample}

    \pgfplotsshowcolormap{jet}

    \matlabcolormaptext
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/blackwhite}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    colormap={blackwhite}{gray(0cm)=(0); gray(1cm)=(1)}
}
\end{codeexample}

    \pgfplotsshowcolormap{blackwhite}
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/bluered}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    colormap={bluered}{
        rgb255(0cm)=(0,0,180); rgb255(1cm)=(0,255,255); rgb255(2cm)=(100,255,0);
        rgb255(3cm)=(255,255,0); rgb255(4cm)=(255,0,0); rgb255(5cm)=(128,0,0)}
}
\end{codeexample}

    \pgfplotsshowcolormap{bluered}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[colormap/bluered]
    \addplot+ [scatter,
         scatter src=x,samples=50]
        {sin(deg(x))};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    \paragraph{Remark:}

    The style |bluered| (re)defines the color map and activates it. \TeX{}
    will be slightly faster if you call |\pgfplotsset{colormap/bluered}| in the
    preamble (to create the color map once) and use |colormap name=bluered|
    whenever you need it. This remark holds for every color map style which
    follows. But you can simply ignore this remark.
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/cool}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    colormap={cool}{rgb255(0cm)=(255,255,255); rgb255(1cm)=(0,128,255); rgb255(2cm)=(255,0,255)}
}
\end{codeexample}

    \pgfplotsshowcolormap{cool}
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/greenyellow}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    colormap={greenyellow}{rgb255(0cm)=(0,128,0); rgb255(1cm)=(255,255,0)}
}
\end{codeexample}

    \pgfplotsshowcolormap{greenyellow}
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/redyellow}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    colormap={redyellow}{rgb255(0cm)=(255,0,0); rgb255(1cm)=(255,255,0)}
}
\end{codeexample}

    \pgfplotsshowcolormap{redyellow}
\end{stylekey}

\begin{stylekey}{/pgfplots/colormap/violet}
    A style which is equivalent to
    %
\begin{codeexample}[code only]
\pgfplotsset{
    colormap={violet}{rgb255=(25,25,122) color=(white) rgb255=(238,140,238)}
}
\end{codeexample}

    \pgfplotsshowcolormap{violet}
\end{stylekey}

\begin{command}{\pgfplotscolormaptoshadingspec\marg{colormap name}\marg{right end size}\marg{\textbackslash macro}}
    A command which converts a colormap into a \PGF{} shading's color
    specification. It can be used in commands like |\pgfdeclare...shading| (see
    the \PGF{} manual~\cite{tikz} for details).

    The first argument is the name of a (defined) colormap, the second the
    rightmost dimension of the specification. The result will be stored in
    \meta{\textbackslash macro}.
    %
\begin{codeexample}[]
    % convert `hot' -> \result
    \pgfplotscolormaptoshadingspec{hot}{8cm}\result
    % define and use a shading in pgf:
    \def\tempb{\pgfdeclarehorizontalshading{tempshading}{1cm}}%
    % where `\result' is inserted as last argument:
    \expandafter\tempb\expandafter{\result}%
    \pgfuseshading{tempshading}%
\end{codeexample}
    %
    The usage of the result \meta{\textbackslash macro} is a little bit
    low-level.


    \paragraph{Attention:}

    \PGF{} shadings are always represented with respect to the RGB color space.
    Consequently, even CMYK \meta{colormap name}s will result in an RGB shading
    specification when using this method.\footnote{In case \PGF{} should someday
    support CMYK shadings and you still see this remark, you can add the macro
    definition \texttt{\textbackslash def\textbackslash
    pgfplotscolormaptoshadingspectorgb\{0\}} to your preamble.}
\end{command}

\begin{command}{\pgfplotscolorbardrawstandalone\oarg{options}}
    A command which draws a |tikzpicture| and a |colorbar| using the current
    colorbar settings inside of it. Its purpose is to simplify the
    documentation.

    Since this |colorbar| is a ``standalone'' picture, it defines the following
    options
    %
\begin{codeexample}[code only]
    point meta min=0,
    point meta max=1000,
    parent axis width/.initial=6cm,
    parent axis height/.initial=6cm,
\end{codeexample}
    %
    before it evaluates \meta{options} and draws the colorbar.
\end{command}

\begin{command}{\pgfplotscolormaptodatafile\oarg{options}\marg{colormap name}\marg{output file}}
    Allows to export |colormap| data to a file.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=1cm,table/col sep=comma]
        \pgfplotscolormaptodatafile{hot}{hot.dat}
    \addplot[red,mark=|]   table[y index=1] {hot.dat};
    \addplot[green,mark=|] table[y index=2] {hot.dat};
    \addplot[blue,mark=|]  table[y index=3] {hot.dat};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[y=1cm,table/col sep=comma]
    \pgfplotscolormaptodatafile{viridis}{viridis.dat}
    \addplot[red]   table[y index=1] {viridis.dat};
    \addplot[green] table[y index=2] {viridis.dat};
    \addplot[blue]  table[y index=3] {viridis.dat};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    Valid \meta{options} are
    %
    \begin{pgfplotskey}{/pgfplots/colormap/output each nth=\meta{num} (initially 1)}
        Allows to downsample the color map by writing only each \meta{num}'s
        entry.
    \end{pgfplotskey}

    \begin{pgfplotskey}{/pgfplots/colormap/output format=\mchoice{cvs,native} (initially csv)}
        The choice \declaretext{csv} generates a CSV file where the first
        column is the offset of the color map and all following are the color
        components.

        The choice \declaretext{native} generates a \TeX{} file which can be
        |\input| in order to define the colormap for use in \PGFPlots{}.
    \end{pgfplotskey}
\end{command}

Note that there are \emph{more available choices} of colormaps in the
associated libraries, name in the |colorbrewer| library and in the |colormaps|
library which need to be loaded by means of
|\usepgfplotslibrary{colorbrewer,colormaps}|.


\subsubsection{Building Colormaps based on other Colormaps}
\label{sec:pgfplots:colormaps:based:on:others}

{
\tikzset{
    /pdflinks/search key prefixes in/.add={}{,/pgfplots/of colormap/},
}
A colormap definition of sorts |colormap=|\marg{name}\marg{color specification}
typically consists of \meta{color specifications} made up from single colors,
each with its own \meta{color model}. As outlined in
Section~\ref{sec:colormap:input:format}, each entry in \meta{color
specification} has the form

    \meta{color model}|(|\meta{position}|)=(|\meta{arguments}|)| or

    \meta{special mode}|(|\meta{position}|)=(|\meta{argument}| of |\meta{colormap name}|)|.

\noindent This section explains how to make use of \meta{special mode} in order
to build |colormap|s based on existing |colormap|s. To this end, \PGFPlots{}
offers the following values inside of a \meta{color specification}:

\begin{enumerate}
    \item
        \declareandlabel{samples of colormap}|(|\meta{position}|)=(|\meta{number}| of |\meta{colormap name}|)| or\\
        \declaretext{samples of colormap}|(|\meta{position}|)=(|\meta{number}|)| or\\
        \declaretext{samples of colormap}|(|\meta{position}|)={|\meta{number}| of |\meta{colormap name}|, |\meta{options}|}|%
            \index{samples of colormap!In colormap specification}%

        This method takes a \meta{colormap name} on input, samples \meta{number}
        colors from it (using a uniform mesh width) and inserts it into the
        currently built |colormap|. It is equivalent to the choice
        |colors of colormap||(|\meta{position}|)=(0,h,...,1000)| with |h|
        chosen such that you get \meta{number} samples positioned at an
        equidistant grid.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap=(4 of viridis)
    },
    colorbar horizontal,
    colormap access=const,
]
\end{codeexample}

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap=(4 of viridis)
    },
    colorbar horizontal,
    colormap access=map,
]
\end{codeexample}

        The special suffix ``| of |\meta{colormap name}'' is optional; it
        defaults to the current value of |colormap name|:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap=(4)
    },
    colorbar horizontal,
    colormap access=const,
]
\end{codeexample}

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap=(4)
    },
    colorbar horizontal,
    colormap access=map,
]
\end{codeexample}

        The argument can be surrounded by round braces or curly braces, both is
        accepted. \PGFPlots{} also accepts a sequence of options inside of the
        argument and curly braces are best applied if options are needed:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap={
            5 of viridis,
            target pos={0,800,850,950,1000},
        }
    },
    colorbar horizontal,
    colormap access=map,
]
\end{codeexample}

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        % simpler alternative:
        % of colormap={viridis,target pos={...}}
        samples of colormap={
            5 of viridis,
            target pos={0,400,500,700,800,1000},
            sample for=const,
        }
    },
    colorbar horizontal,
    colormap access=const,
]
\end{codeexample}

        The use of options inside of the argument is discussed in the next
        subsection, see |of colormap| and |target pos|.

        As with normal color definitions, the \meta{position} argument is
        optional and can be omitted. If it is given, it is used for the first
        encountered item in the list, all others are deduced automatically. If
        both |target pos| and \meta{position} are given, \meta{position} is
        ignored.

        Note that \PGFPlots{} offers a special syntax for |target pos| and a
        sampled colormap:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={
            viridis,
            target pos={0,400,500,700,800,1000},
            sample for=const,
        }
    },
    colorbar horizontal,
    colormap access=const,
]
\end{codeexample}
        %
        This syntax also samples colors from the source colormap (|viridis|
        here). It chooses enough samples to satisfy the given |target pos|; see
        the documentation for `|of colormap|' for details.
    \item
        \declareandlabel{index of colormap}|(|\meta{position}|)=(|\meta{index}| of |\meta{colormap name}|)| or\\
        \declaretext{index of colormap}|(|\meta{position}|)=(|\meta{index}|)|%
            \index{index of colormap!In colormap specification}%

        This key allows to identify a \emph{single} color of \meta{colormap
        name} and use it as part of \meta{color specification}. The
        \meta{index} is a numeric index $0,1,\dotsc,N-1$ where $N$ is the size
        of \meta{colormap name}.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        color=(green),
        index of colormap=(2 of viridis)
    },
    colorbar horizontal,
    colormap access=const,
]
\end{codeexample}

        Note that |index of colormap| is also available as key for drawing
        operations:

        \begin{pgfplotskey}{index of colormap=\meta{index} of \meta{colormap name}}
            Selects the specified color of \meta{colormap name} using the
            special color name `|.|', and assigns |color=.|:
            %
\begin{codeexample}[]
\pgfplotsset{
 colormap={example}{color=(red) color=(blue)}}
\tikz \draw[index of colormap=0 of example] (0,0) -- (1,0);
\end{codeexample}
            %
\begin{codeexample}[]
\pgfplotsset{
 colormap={example}{color=(red) color=(blue)}}
\tikz \fill[index of colormap=1 of example] (0,0) rectangle (1,1);
\end{codeexample}
            %
            Note that some drawing instructions require more than setting
            |color|. In this case, you have to reference the color `|.|' after
            the key:
            %
\begin{codeexample}[]
\pgfplotsset{
 colormap={example}{color=(red) color=(blue)}}
\tikz \shade[
    index of colormap=0 of example,left color=.,
    color of colormap=500 of example,right color=.] (0,0) rectangle (1,1);
\end{codeexample}
        \end{pgfplotskey}

        All special remarks of |samples of colormap| (like curly braces, option
        list support, positions) apply here as well.
    \item
        \declareandlabel{indices of colormap}|(|\meta{position}|)=(|\meta{list of indices}| of |\meta{colormap name}|)| or\\
        \declaretext{indices of colormap}|(|\meta{position}|)=(|\meta{list of indices}|)|%
            \index{indices of colormap!In colormap specification}%

        A convenience key which is equivalent to a sequence of
        |index of colormap||(|\meta{position}|)|, one for each element in
        \meta{list}. The \meta{list} is evaluated using |\foreach|. Note that
        you need round braces around the argument.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        indices of colormap=(0,5,10,12,
          \pgfplotscolormaplastindexof{viridis}
          of viridis)
    },
    colorbar horizontal,
    colormap access=const,
]
\end{codeexample}

        All special remarks of |samples of colormap| (like curly braces, option
        list support, positions) apply here as well.
    \item
        \declareandlabel{color of colormap}|(|\meta{position}|)=(|\meta{value}| of |\meta{colormap name}|)| or\\
        \declaretext{color of colormap}|(|\meta{position}|)=(|\meta{value}|)|%
            \index{color of colormap!In colormap specification}%

        This key allows to interpolate a color within \meta{colormap name} and
        use the result as part of \meta{color specification}. The interpolation
        point is a floating point number in the range $[0,1000]$ and is
        interpolated using |colormap access=map| (i.e.\@ using piecewise linear
        interpolation).

        Note that |color of colormap| is also available as key for drawing
        operations:

        \begin{pgfplotskey}{color of colormap=\meta{value} of \meta{colormap name}}
            Selects the specified color of \meta{colormap name} using the
            special color name `|.|', and assigns |color=.|:
            %
\begin{codeexample}[]
\pgfplotsset{
 colormap={example}{color=(red) color=(blue)}}
\tikz \shade[
    color of colormap=250 of example,left color=.,
    color of colormap=500 of example,right color=.] (0,0) rectangle (1,1);
\end{codeexample}
        \end{pgfplotskey}

        All special remarks of |samples of colormap| (like curly braces, option
        list support, positions) apply here as well.
    \item
        \declareandlabel{colors of colormap}|(|\meta{position}|)=(|\meta{list}| of |\meta{colormap name}|)| or\\
        \declaretext{colors of colormap}|(|\meta{position}|)=(|\meta{list}|)| or\\
        \declaretext{colors of colormap}|(|\meta{position}|)={|\meta{list}| of |\meta{colormap name}|, |\meta{options}|}|%
            \index{colors of colormap!In colormap specification}%

        A convenience key which is equivalent to a sequence of
        |color of colormap||(|\meta{position}|)|, one for each element in
        \meta{list}. The \meta{list} is evaluated using |\foreach|. Note that
        you need round braces around the argument.

\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
      colors of colormap=(0,400,800,900,
          1000 of viridis)
    },
    colorbar horizontal,
    colormap access=const,
]
\end{codeexample}

        Note that |colors of colormap| is also available during |cycle list|
        definitions.

        All special remarks of |samples of colormap| (like curly braces, option
        list support, positions) apply here as well.
    \item \declaretext{of colormap}|(|\meta{position}|)=(|\meta{colormap name}|, |\meta{options}|)|

        Builds a new |colormap| by \emph{sampling} enough colors from the input
        |colormap name|. This mode is one of two methods which samples colors
        from another |colormap|; it is to be preferred if you want to assign
        |target pos|. See also |samples of colormap|; it is simpler if you just
        want to specify a number of samples.

        The syntax `|of colormap=|' is most useful if you want to draw samples
        from another colormap \emph{at specific positions}:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={
            viridis,
            target pos={0,400,500,700,800,1000},
        },
    },
    colorbar horizontal,
    colormap access=map,
]
\end{codeexample}
        %
        Here, \PGFPlots{} parses the \meta{options}. Each unidentified option
        is treated as either a value of `|colormap name|' or as a style
        argument which defines a |colormap| like |colormap/PuOr|. The previous
        example identifies |colormap name=viridis| (since |viridis| is no known
        option) and assigns |target pos|. There are $6$ samples which make up
        the colormap, these are drawn from |viridis|. Note that you do not need
        to specify a \meta{colormap name} in this context. If it is missing,
        the current value of |colormap name| (i.e.\@ the current colormap) will
        be used.

        Similarly, `|of colormap|' can sample a |colormap| for use with
        |colormap access=const|:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={
            viridis,
            target pos={0,400,500,700,800,1000},
            sample for=const,
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
        %
        Note that you \emph{need} to write |sample for=const| in this context
        such that \PGFPlots{} knows that the result is to be used in
        conjunction with |colormap access=const|. The details are specified
        below.

        As with all colormap building blocks, the |target pos| can have an
        arbitrary number range. However, the absolute values are meaningless;
        they are always mapped to the range $[0,1000]$. Only their relative
        distances are of importance when it comes to the |colormap| as such:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={viridis,
            target pos={-10,-3,0,1,2},
            sample for=const,
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
        %
        However, if the |point meta| range equals the colormap definition
        range, you see that they fit exactly:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={viridis,
            target pos={-10,-3,0,1,2},
            sample for=const,
        },
    },
    point meta min=-10,point meta max=2,
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
        %
        Note that you can use |xtick=data| or |ytick=data| inside of the
        |colorbar| styles in order to place tick labels at the |colormap|'s
        positions:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={viridis,
            target pos={-10,-3,0,1,2},
            sample for=const,
        },
    },
    point meta min=-10,point meta max=2,
    colorbar horizontal,
    colorbar style={xtick=data},
    colormap access=const]
\end{codeexample}

        Finally, `|of colormap|' can be used to \emph{copy} another |colormap|:
        if there are no suitable hints how to build a new |colormap|,
        \PGFPlots{} copies the input map:
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={viridis},
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}

        The \meta{options} are accepted by all colormap building blocks: you
        can also specify them after |samples of colormap| or
        |colors of colormap| if needed.

        The following options are available:

        \begin{pgfplotskey}{of colormap/target pos=\marg{position(s)} (initially empty)}
            Allows to define the \meta{position} for zero, one, or more of the
            involved colors. An empty value means to use the argument in round
            braces `|(|\meta{position}|)|' in the definition, for example the
            value $100$ in |color of colormap(100)=(4)|. This is sufficient if
            there is just one color involved. However, if |target pos| has a
            non-empty value, it overrides the |(|\meta{position}|)| argument.

            The key |target pos| is primarily intended to provide positions for
            more than one color definition, in particular in the context of
            `|of colormap|'. In this context, as many \meta{position(s)} as
            specified are used.

            If you have |colors of colormap| and a non-empty value of
            |target pos|, \PGFPlots{} will use as many |target pos|itions as
            available. If there are too few to cover all involved colors, the
            remaining ones are deduced automatically. More precisely:
            \PGFPlots{} will use the current mesh width as distance to the
            previous position. The ``current mesh width'' is defined as the
            smallest difference between adjacent positions. Excess positions
            will be ignored (and a warning is written into the logfile).

            Note that |target pos| requires attention when used together with
            |colormap access=const|: in this case, there are \emph{intervals}
            with constant color and the positions become interval boundaries.
            Consequently, $N$ elements in |target pos| make up $N-1$ different
            colors!

            Note that |target pos| as option to |samples of colormap| is also
            possible. However, you have to specify all required positions and
            it is an error if the number does not match. If you also combine
            this case with |sample for=const|, you need $N+1$ positions for $N$
            samples.
        \end{pgfplotskey}

        \begin{pgfplotskey}{of colormap/sample for=\mchoice{default,const} (initially default)}
            This key allows to configure |samples of colormap| such that the
            resulting |colormap| is suitable for dedicated values of
            |colormap access|.

            In particular, it allows to optimize \meta{colormap definitions}
            which rely on \emph{sampling} for the case |colormap access=const|.

            Note that the case |colormap access|$\neq$|const| typically
            requires no modification to this key and works best with the
            defaults.

            The strategy |colormap access=const| means that colors are
            associated with entire \emph{intervals} and no longer with single
            positions in the |colormap|. In this context, you have to write
            |sample for=const| such that \PGFPlots{} handles that correctly.

            Here is the reference of |colormap|s and their significance with
            respect to |sample for|:
            %
            \begin{itemize}
                \item In general, a |colormap| can be used with any value
                    of |colormap access|. If there are no positions in the
                    \meta{colormap definition} (neither in round braces nor
                    in |target pos|), this works out of the box without any
                    special attention.
                    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap={
            5 of viridis,
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
                    %
                \item As soon as there are positions, \PGFPlots{} has a
                    conflict if the colormap is used in the context of
                    |colormap access=const|: it cannot enlarge the
                    displayed limit, but it cannot respect both the given
                    positions \emph{and} the required number of colors! It
                    has the choice to either omit one color, or to add an
                    artificial position and rescale all other positions.
                \item The default strategy in \PGFPlots{} in the presence
                    of |colormap access=const| and input positions is:
                    \PGFPlots{} chooses to keep the input positions and
                    omit one color.
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={
            viridis,
            target pos={0,500,850,950,1000},
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}

                    Technically, this means that it implicitly sets
                    |colormap access/extra interval width=0| (the default is
                    |colormap access/extra interval width=h|). The color
                    associated with $1000$ has no interval and is essentially
                    invisible.

                    Restoring |colormap access/extra interval width=h| results
                    in rescaled positions which is typically not what you want:
                    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap={
            5 of viridis,
            target pos={0,500,850,950,1000},
        },
    },
    colormap access/extra interval width=h,
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
                    %
                \item Finally, \PGFPlots{} offers |sample for=const|.

                    Applying |sample for=const| to `|of colormap|' ensures that
                    any given positions are respected. To this end, it reduces
                    the number of available colors, but modifies the sampling
                    procedure such that the entire input color range is visible
                    in the result:
                    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={
            viridis,
            target pos={0,500,850,950,1000},
            sample for=const,
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
                    %
                    Here, the result has $4$ colors, but the rightmost color is
                    also the rightmost color of the input map |viridis|. Note
                    that |of colormap| has assigned an invisible color to the
                    position $1000$: this dummy color is defined to be the
                    rightmost color of |viridis|. That means that if you define
                    a |colormap| with |sample for=const| and use it with
                    |colormap access=map|, the right end of the interval will
                    be longer than expected:
                    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        of colormap={
            viridis,
            target pos={0,500,850,950,1000},
            sample for=const,
        },
    },
    colorbar horizontal,
    colormap access=map]
\end{codeexample}

                    The strategy |sample for=const| applied to
                    |samples of colormap| works in a similar way. Keep in mind
                    that this combination requires to either omit |target pos|
                    or to add \emph{exactly} $N+1$ target positions:
                    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        samples of colormap={
            5 of viridis,
            target pos={0,100,500,850,950,1000},
            sample for=const,
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}

                    This results in correctly respected positions and a fully
                    respected range of the input colormap.
            \end{itemize}

            The key |sample for| applies whenever a \meta{colormap definition}
            involves sampling (that means: only for |of colormap| and
            |samples of colormap|). It does not apply for explicitly fixed
            colors. Its effect is that the number of samples is reduced by~$1$
            and the last provided sample is replicated once.

            See also |colormap access/extra interval width|.
        \end{pgfplotskey}

        \begin{pgfplotskey}{of colormap/colormap access=\marg{argument}}
             An alias for |/pgfplots/colormap access=|\marg{argument}.
        \end{pgfplotskey}

        \begin{pgfplotskey}{of colormap/source range=\marg{min:max} (initially 0:1000)}
             Defines the source range for interpolation-based specifications,
             i.e.\@ for |color of colormap| and |const color of colormap|. It
             defaults to |0:1000| which means that only values in the interval
             $[0,1000]$ can be provided.

             Changing the value allows to use any number range in order to
             identify numbers.
             %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        colors of colormap={
            -30000,-10000,0,100000,110000 of viridis,
            source range=-30000:120000,
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
            %
        \end{pgfplotskey}

%        \begin{pgfplotskey}{of colormap/source name=\marg{colormap name} (initially empty)}
%            The name of the source color map. An empty value means ``use the
%            current value of |colormap name|''.
%        \end{pgfplotskey}

        \noindent Note that these building blocks can be combined as often as
        needed. This allows to combine different colormaps:
        %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    point meta min=-7046,
    point meta max=2895,
    colormap={whiteblue}{color=(blue) color=(white)},
    colormap={gb}{color=(green) color=(yellow)
        color=(brown)},
    colormap={CM}{
        of colormap={
            whiteblue,
            target pos={-7046,-6000,-5000,-3000,
                -1000,-750,-500,-250,-100,-50,0},
            sample for=const,
        },
        of colormap={
            gb,
            target pos={10,100,200,500,1000,1100,
                1200,1500,2000,2895},
            sample for=const,
        },
    },
    colorbar horizontal,
    colormap access=const]
\end{codeexample}
        %
        \noindent The previous example first defines the two simple colormaps
        |whiteblue| and |gb|. These are merely used as building blocks; they
        are not used for the visualization. Finally, the colormap |CM| consists
        of two |of colormap| specifications which resample the building blocks
        and assign specific |target pos|itions.

        \begin{pgfplotskeylist}{%
            of colormap/target pos min=\marg{lower limit} (initially empty),
            of colormap/target pos min*=\marg{lower limit} (initially empty),
            of colormap/target pos max=\marg{upper limit} (initially empty),
            of colormap/target pos max*=\marg{upper limit} (initially empty)%
        }
            These keys allow to \emph{modify} the argument of |target pos|.
            Their primary use is to simplify writing style definitions.
            Consequently, most users may want to ignore these keys and skip
            their documentation. The keys are unnecessary if the argument of
            |target pos| is used directly.

            The versions without star (|target pos min| and |target pos max|)
            discard all elements of |target pos| which are outside of the
            bounds. The starred versions (|target pos min*| and
            |target pos max*|) also discard all which do not fit, but they
            ensure that the limit is part of |target pos| after the filtering.

            These filtering limits come in handy if you want to select matching
            positions from a previously defined |target pos|, for example if
            the same |target pos| is part of a reusable style:
            %
\begin{codeexample}[width=8cm]
\pgfplotsset{
    of colormap/ocean height/.style={
        target pos={-12000,-10000,-6000,-5000,-3000,
            -1000,-750,-500,-250,-100,-50,0,10,100,
            200,500,1000,1100,1200,1500,2000,4000,
            6000,8000},
    },
}
\pgfplotscolorbardrawstandalone[
  point meta min=-7046,
  point meta max=2895,
  colormap={whiteblue}{color=(blue) color=(white)},
  colormap={gb}{color=(green) color=(yellow)
      color=(brown)},
  colormap={CM}{
      of colormap={
        whiteblue,
        ocean height,
        target pos min*=
          \pgfkeysvalueof{/pgfplots/point meta min},
        target pos max=0,
        sample for=const,
      },
      of colormap={
        gb,
        ocean height,
        target pos min=0.1,
        target pos max*=
          \pgfkeysvalueof{/pgfplots/point meta max},
        sample for=const,
      },
  },
  colorbar horizontal,
  colormap access=const]
\end{codeexample}
            %
            \noindent The example defines a style named `|ocean height|' with a
            suitable list of positions somewhere in the document. Then, it
            defines a colormap `|CM|' which makes use of these keys -- but only
            in the range $[-7046,2895]$, and with a special combination of two
            other |colormap|s. The first |of colormap| specification selects
            only those target positions which fall in the range $[-7046,0]$ and
            ensures that $-7046$ actually becomes an element of |target pos|.
            The second |of colormap| specification selects all in the range
            $[0.1,2895]$ and ensures that $2895$ becomes an element of
            |target pos|. Note that the $0.1$ merely serves as indicator to
            \emph{not} select $0$ again. Thus, the selection is essentially
            equivalent to
            %
\begin{codeexample}[code only]
...
target pos={-7046,-6000,-5000,-3000,-1000,-750,-500,-250,-100,-50,0}
...
target pos={10,100,200,500,1000,1100,1200,1500,2000,2895}
\end{codeexample}
            %
            with the exception that the predefined style defined a list of
            suitable positions. The \emph{colors} taken from |whiteblue| are
            the same as if you would write |samples of colormap={11}|, i.e.\@
            they are drawn uniformly from the input colormap. Only their
            target position in the result is modified. The same applies to
            the colors taken from |bg|; they are drawn uniformly and moved to
            the prescribed boundaries.

            \PGFPlots{} uses these keys in order to implement
            |contour filled|.

            Note that a colormap definition is not bound to specific
            coordinates, although this makes a lot of sense in the context of
            |contour| plots. In principle, you can use the resulting colormap
            in any context, just as all other colormaps:
            %
\begin{codeexample}[]
\pgfplotsset{
  colormap={whiteblue}{color=(blue) color=(white)},
  colormap={gb}{color=(green) color=(yellow)
      color=(brown)},
  of colormap/ocean height/.style={
      target pos={-12000,-10000,-6000,-5000,-3000,
          -1000,-750,-500,-250,-100,-50,0,10,100,
          200,500,1000,1100,1200,1500,2000,4000,
          6000,8000},
  },
  colormap={CM}{
      of colormap={
          whiteblue,
          ocean height,
          target pos max=0,
          sample for=const,
      },
      of colormap={
          gb,
          ocean height,
          target pos min=0.1,
          sample for=const,
      },
  },
}
\begin{tikzpicture}
\begin{axis}[small,colorbar]
    \addplot3[surf] {x*y};
\end{axis}
\end{tikzpicture}
~
\begin{tikzpicture}
\begin{axis}[small,colorbar,
    colorbar style={colormap access=const}
]
    \addplot3[surf,shader=interp,colormap access=const] {x*y};
\end{axis}
\end{tikzpicture}
\end{codeexample}
            %
            Note that the last example has the same look as if it was
            produced by |contour filled|. The difference is that
            |contour filled| takes the input colormap and
            \emph{resamples} it according to the selected contour
            levels. The example above is just a ``normal'' surface
            plot with a special colormap.
        \end{pgfplotskeylist}
    \item
        \declareandlabel{const color of colormap}|(|\meta{position}|)=(|\meta{value}| of |\meta{colormap name}|)|%
            \index{const color of colormap!In colormap specification}%

        This key is almost the same as |color of colormap| mentioned above, but
        it uses the same functionality as |colormap access=piecewise constant|
        while it determines colors from the \emph{source} color map (including
        |colormap access/extra interval width|). Note that the resulting
        colormap can still be used with any value of |colormap access|,
        including both |colormap access=const| and |colormap access=map|.

        Note that |const color of colormap| is also available as key for
        drawing operations:

        \begin{pgfplotskey}{const color of colormap=\meta{value} of \meta{colormap name}}
           Selects the specified color of \meta{colormap name} using the
           special color name `|.|', and assigns |color=.|:
            %
\begin{codeexample}[]
\pgfplotsset{
  colormap={example}{color=(red) color=(blue) color=(yellow)}}
\tikz \fill[const color of colormap=50 of example] (0,0) rectangle (1,1);
\tikz \fill[const color of colormap=750 of example] (0,0) rectangle (1,1);
\end{codeexample}
        \end{pgfplotskey}

        All special remarks of |samples of colormap| (like curly braces, option
        list support, positions) apply here as well.
    \item
        \declareandlabel{const colors of colormap}|(|\meta{position}|)=(|\meta{list}| of |\meta{colormap name}|)|%
            \index{const colors of colormap!In colormap specification}%

        A convenience key which is equivalent to a sequence of
        |const color of colormap(|\meta{position}|)|, one for each element in
        \meta{list}. The \meta{list} is evaluated using |\foreach|.

        Note that |const colors of colormap| is also available during
        |cycle list| definitions.

        All special remarks of |samples of colormap| (like curly braces, option
        list support, positions) apply here as well.
\end{enumerate}

\begin{pgfplotskey}{colormap access/extra interval width=\marg{fraction} (initially h)}
    \paragraph{Attention:}

    this key is supposed to be a technical part of the implementation. You may
    want to skip its documentation as it typically works out of the box. You
    only need to respect |sample for|.

    This key applies \emph{only} to |colormap access=piecewise constant|: it
    ensures that each color in the |colormap| receives its own \emph{interval}.
    This ensures that each color is actually visible in the output. Thus, each
    provided color resembles an \emph{interval}. This is different from
    |colormap access=map| where each provided color resembles an \emph{interval
    boundary}.

    Normally, \PGFPlots{}, activates this feature if and only if it has
    automatically computed positions. Consequently, the following example
    implicitly uses |extra interval width=h| (the default):
    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        color=(blue)
        color=(red)
        color=(black)
    },
    colorbar horizontal,
    colorbar style={xtick=data},
    colormap access=const,
]
\end{codeexample}

    As soon as you provide positions manually, \PGFPlots{} defaults to
    |extra interval width=0| in order to respect the input settings:
    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        color(0)=(blue)
        color(500)=(red)
        color(1000)=(black)
    },
    colorbar horizontal,
    colorbar style={xtick=data},
    colormap access=const,
]
\end{codeexample}
    %
    \noindent Note that the positions make up the input nodes for the
    |colormap| with the consequence that the last color is \emph{unused}; it
    merely serves as interval boundary. In this context, ``provide manually''
    means positions in round braces or a non-empty value of |target pos|.

    In order to override the input positions and get an extra interval, you
    have to set the option:
    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={example}{
        color(0)=(blue)
        color(500)=(red)
        color(1000)=(black)
    },
    colorbar horizontal,
    colorbar style={xtick=data},
    colormap access/extra interval width=h,
    colormap access=const,
]
\end{codeexample}
    %
    Note how the extra interval of |colormap access=const| modifies the
    positions of the colormap definition: they are all shifted to the left and
    the chosen input positions are scaled accordingly. This becomes more
    apparent in the following example. First, we generate a colormap with the
    default settings which disables the extra interval, but omits the last
    (brightest) color:
    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={nonuniform}{
        of colormap={
            viridis,
            target pos={0,200,300,500,700,1000}
        },
    },
    colorbar horizontal,
    colormap access=const,
    colorbar style={xtick=data,font=\tiny,
        /pgf/number format/precision=0},
    colormap access=const,
]
\end{codeexample}

    Next, we explicitly enable the extra interval and see that the input
    positions are scaled to the left. Note that they keep their relative
    distances, but the last color of the colormap is finally visible:
    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={nonuniform}{
        of colormap={
            viridis,
            target pos={0,200,300,500,700,1000}
        },
    },
    colorbar horizontal,
    colormap access=const,
    colormap access/extra interval width=h,
    colorbar style={xtick=data,font=\tiny,
        /pgf/number format/precision=0},
    colormap access=const,
]
\end{codeexample}

    The last example relies on |of colormap| and a \emph{sampling} procedure.
    In this context, \PGFPlots{} offers |sample for=const| which results in the
    expected look:
    %
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={nonuniform}{
        of colormap={
            viridis,
            target pos={0,200,300,500,700,1000},
            sample for=const,
        },
    },
    colorbar horizontal,
    colormap access=const,
    colorbar style={xtick=data,font=\tiny,
        /pgf/number format/precision=0},
    colormap access=const,
]
\end{codeexample}
    %
    Please refer to the documentation of |sample for|.

    The default width of this interval is the mesh width of the color map (the
    value \declaretext{h}), i.e.\@ it will always be as large as the other
    intervals. If the color map has nonuniform distances, the smallest
    encountered mesh width is used for the extra interval. This can be seen if
    we omit the key and add some artificial color at the right end manually --
    we only need to ensure that the rightmost interval has the correct length.
    In our example above, the smallest mesh width is $100$, so we can generate
    an equivalent result by means of
    %
    \index{Color maps!Non uniform}
\begin{codeexample}[]
\pgfplotscolorbardrawstandalone[
    colormap={nonuniform}{
        of colormap={
            viridis,
            target pos={0,200,300,500,700,1000}
        },
        color(1100)=(red)
    },
    colorbar horizontal,
    colormap access=const,
    colorbar style={xtick=data,font=\tiny,
        /pgf/number format/precision=0},
    colormap access=const,
]
\end{codeexample}
    %
    \noindent As already mentioned, |colormap access=const| ignores the
    rightmost color (``|red|''). Note that this approach is almost the same as
    the internal implementation of |sample for=const|.

    The value of |colormap access/extra interval width=|\meta{fraction} can
    also be used to customize the width of the artificial interval: it is a
    fraction of the total width and accepted values are $0\le
    $\meta{fraction}$\le 0.9$ where $0$ disables the extra interval and $0.9$
    corresponds to $90\%$ of the resulting width. Any non-$0$ value for
    \meta{fraction} creates an extra interval and its width is \meta{fraction}
    percent of the entire color map. The special magic value
    |colormap access/extra interval width=|\declaretext{h} will use the
    colormap's mesh width. If the colormap has nonuniform distances, it will
    use the smallest encountered mesh width. This is the default.

    Note that \meta{fraction} is a property of the |colormap|. The key defines
    it for the \emph{current} color map only. Defining a new |colormap| uses
    the default width for the new |colormap| (but keeps the configured value
    for the old |colormap|).


    \paragraph{Attention:}

    at the time of this writing, uniform color maps only support the default
    interval width `|h|' and \meta{fraction}$=0$, further customization is only
    possible for nonuniform color maps. If you ever need to work around this
    limitation, you should file a feature requests and move one of your color
    position until the colormap becomes a nonuniform colormap.
\end{pgfplotskey}

}%


\subsubsection{Choosing a Colormap Entry as Normal Color}

\begin{pgfplotskeylist}{%
    color of colormap=\meta{value},
    color of colormap=\meta{value} of \meta{colormap name}%
}
    [See also Section~\ref{sec:pgfplots:colormaps:based:on:others} on
    page~\pageref{sec:pgfplots:colormaps:based:on:others} for how to employ
    this within |colormap| definitions]

    Defines the \tikzname{} |color| to be the \meta{value} of \meta{colormap
    name}. If \meta{colormap name} is omitted, the value of |colormap name| is
    evaluated (i.e.\@ the current colormap is used).

    The argument \meta{value} is expected to be a number in the range
    $[0,1000]$ where $0$ resembles the lower end of the color map and $1000$
    the upper end.

    \pgfkeysgetvalue{/pgfplots/colormap name}\colormapname
    Current colormap (\colormapname): \pgfplotsshowcolormap{\colormapname}

\begin{codeexample}[]
\tikz\fill [color of colormap={800}, thick,
    draw=.!60!black]
        (0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}

    The key computes the requested color and calls |color=.|. Keep in mind that
    the magic color name `|.|' always reflects the ``current color'', i.e.\@
    the result of |color=|\meta{some color}. Also keep in mind that |color| is
    a \tikzname{} command which merely defines the color, you also have to
    provide one of `|draw|' or `|fill|' such that it has an effect. Since `|.|'
    is a normal color, we can write |draw=.!60!black| to combine it with
    another color.

    viridis: \pgfplotsshowcolormap{viridis}

\begin{codeexample}[]
\pgfplotsset{colormap name=viridis}
\tikz\fill [color of colormap={1000},thick,
    draw=.!60!black]
        (0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}

\begin{codeexample}[]
\tikz\fill [color of colormap={300 of viridis},thick,
    draw=.!60!black]
        (0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}

    The argument \meta{colormap name} is either a valid argument of
    |colormap name| \emph{or} a style name like |colormap/cool|:

    cool: \pgfplotsshowcolormap{cool}

\begin{codeexample}[]
\tikz\fill [color of colormap={300 of colormap/cool},
    thick,draw=.!60!black]
        (0,0) -- (1,1) -- (2,1) circle (10pt);
\end{codeexample}

    This last syntax allows to evaluate colormaps lazily. However, if you have
    many references to the same colormap, it makes sense to write
    |\pgfplotsset{colormap/cool}| first followed by many references to
    |color of colormap={... of cool}| in order to avoid unnecessary lazy
    evaluations.

    It is possible to write lots of invocations without an explicit
    \meta{colormap name}, i.e.\@ lots of invocations of sorts
    |color of colormap=|\meta{value}. They will all use the |colormap name|
    which is active at that time.

    Note that there are actually keys with two key prefixes:
    |/pgfplots/color of colormap| and an alias |/tikz/color of colormap|. This
    allows to use the keys both for plain \tikzname{} graphics and for
    \PGFPlots{}.

    See also |colormap access=map|.
\end{pgfplotskeylist}

\begin{pgfplotskeylist}{%
    index of colormap=\meta{index},
    index of colormap=\meta{index} of \meta{colormap name}%
}
    [See also Section~\ref{sec:pgfplots:colormaps:based:on:others} on
    page~\pageref{sec:pgfplots:colormaps:based:on:others} for how to employ
    this within |colormap| definitions]

    A variant of |color of colormap| which accesses the \meta{colormap name} by
    index. Consequently, the argument \meta{index} is an integer number in the
    range $0,\dotsc,N-1$ where $N$ is the number of colors which define the
    \meta{colormap name}. A \meta{index} outside of this range is automatically
    clipped to the upper bound.

\begin{codeexample}[]
    \pgfplotsset{colormap/jet}
\foreach \i in {
    0,...,\pgfplotscolormaplastindexof{jet}
}{
    \tikz\fill [
        index of colormap={\i of jet},
        thick,
        draw=.!60!black,
    ] (0,0) rectangle (10pt,6pt);
}
\end{codeexample}

    \begin{command}{\pgfplotscolormapsizeof\marg{colormap name}}
        Expands to the number of colors which make up \meta{colormap name}.

        If the argument \meta{colormap name} is an unknown colormap, it expands
        to $0$.
    \end{command}

    \begin{command}{\pgfplotscolormaplastindexof\marg{colormap name}}
        Expands to the last index of \meta{colormap name}, i.e.\@ it is a
        convenience method to access $N-1$.

        If the argument \meta{colormap name} is an unknown colormap, it expands
        to $-1$.
    \end{command}

    See also |colormap access=direct|.
\end{pgfplotskeylist}

\begin{pgfplotskeylist}{%
    const color of colormap=\meta{value},
    const color of colormap=\meta{value} of \meta{colormap name}%
}
    [See also Section~\ref{sec:pgfplots:colormaps:based:on:others} on
    page~\pageref{sec:pgfplots:colormaps:based:on:others} for how to employ
    this within |colormap| definitions]

    Defines the \tikzname{} |color| to be the \meta{value} of \meta{colormap
    name}. If \meta{colormap name} is omitted, the value of |colormap name| is
    evaluated (i.e.\@ the current colormap is used).

    This key is almost the same as |color of colormap|, except that it uses
    |colormap access=piecewise constant| in order to determine the interpolated
    value.
\end{pgfplotskeylist}


\subsection{Cycle Lists -- Options Controlling Line Styles}
\label{sec:cycle:list}

\begin{pgfplotskeylist}{cycle list=\marg{list},cycle list name=\marg{name}}
    Allows to specify a list of plot specifications which will be used for each
    \hbox{|\addplot|} command without explicit plot specification. Thus, the
    currently active |cycle list| will be used if you write either
    |\addplot+|\oarg{keys}| ...;| or if you \emph{don't} use square brackets as
    in |\addplot|\oarg{explicit plot specification}| ...;|.

    The list element with index~$i$ will be chosen where~$i$ is the index of
    the current |\addplot| command (see also the |cycle list shift| key which
    allows to use $i+n$ instead). This indexing does also include plot commands
    which don't use the |cycle list|.

    There are several possibilities to change the currently active
    |cycle list|:


    \subsubsection{Predefined Lists}

    Use one of the predefined lists,\footnote{In an early version, these lists
    were called \texttt{\textbackslash coloredplotspeclist} and
    \texttt{\textbackslash blackwhiteplotspeclist} which appeared to be
    unnecessarily long, so they have been renamed. The old names are still
    accepted, however.}
    %
    \begin{itemize}
        \item \declareandlabel{color} (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=color,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
            %
        \item \declareandlabel{exotic} (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=exotic,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

        \item \declareandlabel{black white} (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=black white,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
            %
        \item \declareandlabel{mark list} (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=mark list,
]
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

            The |mark list| always employs the current color, but it doesn't
            define one (the \verbpdfref{\addplot+} statement explicitly sets
            the current color to |blue|).

            The |mark list| is especially useful in conjunction with
            |cycle multi list| which allows to combine it with other lists (for
            example |linestyles| or a list of colors).
        \item \declareandlabel{mark list*} A list containing only markers. In
            contrast to |mark list|, all these markers are filled. They are
            defined as (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=mark list*,
]
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
  \addplot+ [blue] coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
            %
            Similar to |mark list|, the |mark list*| always employs the current
            color, but it doesn't define one (see above for the
            \verbpdfref{\addplot+}).
        \item \declareandlabel{color list} (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=color list,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

            The |cycle list name=color| choice also employs markers whereas
            |color list| uses \emph{only} colors.

        \item \declareandlabel{linestyles} (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=linestyles,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
            %
        \item \declareandlabel{linestyles*} contains more dotted line styles
            than |linestyles| (from top to bottom)
            %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    stack plots=y,stack dir=minus,
    cycle list name=linestyles*,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
        \item \declareandlabel{auto} The |cycle list name=auto| always
            denotes the most recently used cycle list activated by
            |cycle list| or |cycle list name|.
    \end{itemize}

    The definitions of all predefined cycle lists follow (see the end of this
    paragraph for a syntax description).
        %
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{color}{
    blue,every mark/.append style={fill=blue!80!black},mark=*\\
    red,every mark/.append style={fill=red!80!black},mark=square*\\
    brown!60!black,every mark/.append style={fill=brown!80!black},mark=otimes*\\
    black,mark=star\\
    blue,every mark/.append style={fill=blue!80!black},mark=diamond*\\
    red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\
    brown!60!black,densely dashed,every mark/.append style={
        solid,fill=brown!80!black},mark=square*\\
    black,densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\
    blue,densely dashed,mark=star,every mark/.append style=solid\\
    red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\
}
\end{codeexample}

\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{black white}{
    every mark/.append style={fill=gray},mark=*\\
    every mark/.append style={fill=gray},mark=square*\\
    every mark/.append style={fill=gray},mark=otimes*\\
    mark=star\\
    every mark/.append style={fill=gray},mark=diamond*\\
    densely dashed,every mark/.append style={solid,fill=gray},mark=*\\
    densely dashed,every mark/.append style={solid,fill=gray},mark=square*\\
    densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\
    densely dashed,every mark/.append style={solid},mark=star\\
    densely dashed,every mark/.append style={solid,fill=gray},mark=diamond*\\
}
\end{codeexample}

\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{exotic}{
    teal,every mark/.append style={fill=teal!80!black},mark=*\\
    orange,every mark/.append style={fill=orange!80!black},mark=square*\\
    cyan!60!black,every mark/.append style={fill=cyan!80!black},mark=otimes*\\
    red!70!white,mark=star\\
    lime!80!black,every mark/.append style={fill=lime},mark=diamond*\\
    red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\
    yellow!60!black,densely dashed,
        every mark/.append style={solid,fill=yellow!80!black},mark=square*\\
    black,every mark/.append style={solid,fill=gray},mark=otimes*\\
    blue,densely dashed,mark=star,every mark/.append style=solid\\
    red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\
}
\end{codeexample}

\begin{codeexample}[code only]
% note that "." is the currently defined Tikz color.
\pgfplotscreateplotcyclelist{mark list}{
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=square*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=triangle*\\
    every mark/.append style={solid},mark=star\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=diamond*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill!40},mark=otimes*\\
    every mark/.append style={solid},mark=|\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=pentagon*\\
    every mark/.append style={solid},mark=text,text mark=p\\
    every mark/.append style={solid},mark=text,text mark=a\\
}
\end{codeexample}
    %
    \noindent In this context, a common fill color expression can be customized
    using |mark list fill|:
    %
    \begin{pgfplotskey}{mark list fill=\marg{color} (initially .!80!black)}
        Allows to customize the fill color for the |mark list| and
        |mark list*|.

        For example, if you have |black| as color, the alternative choice
        |mark list fill=.!50!white| will produce much better results.
    \end{pgfplotskey}

    \begin{command}{\pgfplotsmarklistfill}
        Expands to |\pgfkeysvalueof{||/pgfplots/mark list fill||}|.
    \end{command}
    %
\begin{codeexample}[code only]
% note that "." is the currently defined Tikz color.
\pgfplotscreateplotcyclelist{mark list*}{
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=square*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=triangle*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfsquare*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=pentagon*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfcircle*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill,rotate=180},mark=halfdiamond*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill!40},mark=otimes*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=diamond*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfsquare right*\\
    every mark/.append style={solid,fill=\pgfplotsmarklistfill},mark=halfsquare left*\\
}
\end{codeexample}

\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{color list}{
    red,blue,black,yellow,brown,teal,orange,violet,cyan,green!70!black,magenta,gray
}
\end{codeexample}

\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{linestyles}{solid,dashed,dotted}
\pgfplotscreateplotcyclelist{linestyles*}{solid,dashed,dotted,dashdotted,dashdotdotted}
\end{codeexample}


    \subsubsection{Defining Own Cycle Lists}

    The second choice for cycle lists is to provide each entry directly as
    argument to |cycle list|,
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[
    cycle list={
        {blue,mark=*},
        {red,mark=square},
        {dashed,mark=o},
        {loosely dotted,mark=+},
        {brown!60!black,mark=otimes*,
            mark options={fill=brown!40},
        }% <-- don't add a comma here
    },
]
    \plotcoords
    \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$}
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
    %
    (This example list requires |\usetikzlibrary{plotmarks}|).

    The input format is described below in more detail.


    \subsubsection{Defining and Labeling Own Cycle Lists}

    The last method for cycle lists is to combine the define \emph{named} cycle
    lists in the preamble and use them with `|cycle list name|':
    %
    \begin{command}{\pgfplotscreateplotcyclelist\marg{name}\marg{list}}%
    \end{command}
    %
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{mylist}{
    {blue,mark=*},
    {red,mark=square},
    {dashed,mark=o},
    {loosely dotted,mark=+},
    {brown!60!black,mark options={fill=brown!40},mark=otimes*}% <-- don't add a comma here
}
...
\begin{axis}[cycle list name=mylist]
    ...
\end{axis}
\end{codeexample}


    \subsubsection{Defining Cycle Lists: Input Format}

    A |cycle list| is defined by key--value pairs of sorts
    |cycle list=|\marg{list} or by the equivalent macro outlined above,
    |\pgfplotscreateplotcyclelist|\marg{name}\marg{list}.

    In this context, the argument \meta{list} is usually a comma separated list
    of lists of style keys like colors, line styles, marker types and marker
    styles. This ``comma list of comma lists'' structure requires to
    encapsulate the inner list using curly braces:
    %
\begin{codeexample}[code only]
\pgfplotscreateplotcyclelist{mylist}{
    {blue,mark=*},
    {red,mark=square},
    {dashed,mark=o},
    {loosely dotted,mark=+},
    {brown!60!black,mark options={fill=brown!40},mark=otimes*}% <-- don't add a comma here
}
\end{codeexample}
    %
    Alternatively, one can terminate the inner lists (i.e.\@ those for one
    single plot) with `|\\|':
    %
\begin{codeexample}[code only]
\begin{axis}[
    cycle list={
        blue,mark=*\\
        red,mark=square\\
        dashed,mark=o\\
        loosely dotted,mark=+\\
        brown!60!black,mark options={fill=brown!40},mark=otimes*\\
    },
]
...
\end{axis}
\end{codeexample}
    %
    In this case, the \emph{last} entry also needs a terminating `|\\|', but
    one can omit braces around the single entries.


    \subsubsection{Manipulating Associations of Cycle Lists to Plots}

    \begin{pgfplotskey}{cycle list shift=\marg{integer} (initially empty)}
        Allows to \emph{shift} the index into the |cycle list|. If
        \meta{integer} is $n$, the list element $i+n$ will be taken instead of
        the $i$th one. Remember that $i$ is the index of the current |\addplot|
        command (starting with~$0$).

        Since a |cycle list| is queried \emph{immediately} when |\addplot| (or
        |\addplot+|) is called, you can adjust the |cycle list shift| for
        selected plots:
        %
\begin{codeexample}[code only]
    \pgfplotsset{cycle list shift=3}
\addplot ...

    \pgfplotsset{cycle list shift=-1}
\addplot ...
\end{codeexample}

        \paragraph{Special case:}

        If the result is negative, $i+n <0$, the list index $-(i+n)$ will be
        taken. For example, |cycle list shift=-10| and $i<10$ will result in
        list index $10-i$. Note that you can use |reverse legend| to reverse
        legends, so this feature is probably never needed.
    \end{pgfplotskey}


    \subsubsection{Defining Cycle Lists based on Color Maps}

    In addition to defining |cycle list|s from scratch, \PGFPlots{} supports
    dedicated input definitions of |cycle list=|\meta{list} which allow to
    acquire values from an existing |colormap|. In this case, \meta{list}
    contains keys enclosed in square brackets:
    \index{Colormap!Convert into Cycle list}

{%
\pgfplotsset{
    % ATTENTION: this is documented in this manual!
    cycle from colormap manual style/.style={
        x=3cm,y=10pt,ytick=\empty,
        colorbar style={x=,y=,ytick=\empty},
        point meta min=0,point meta max=1,
        stack plots=y,
        y dir=reverse,colorbar style={y dir=reverse},
        every axis plot/.style={line width=2pt},
        legend entries={0,...,20},
        legend pos=outer north east,
    },
}

    The first syntax, \declareandlabel{of colormap}, allows to convert the
    colors of a |colormap| to a |cycle list|. It can be specified without
    argument by means of |cycle list={[of colormap]}| in order to take the
    value of the most recently assigned |colormap name| (i.e.\@ the current
    |colormap|). It can also be specified as |cycle list={[of colormap=name]}|
    in which case it will use the specified |colormap name=name|. In both
    cases, the definition merely converts the colors as they are found in the
    colormap into the cycle list, i.e.\@ there is no interpolation involved.
    Applying this to the default |colormap name=hot| which has~$4$ colors
    results in the following example:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap name=hot,colorbar,
    cycle list={[of colormap]},
    %
    cycle from colormap manual style,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    Note that since |hot| has $4$ colors, the |cycle list| also contains $4$
    entries which are repeated every $4$ plots.

    The second possibility resembles |samples of colormap|: it expects
    \declaretext{samples of colormap}|=|\marg{number}| of |\meta{colormap name}.
    It chooses \meta{number} samples of the selected colormap.

    The third possibility is similar to |color of colormap|: it expects
    \declareandlabel{colors of colormap}|=|\marg{list} or
    |colors of colormap=|\marg{list}| of |\meta{colormap name}. This choice
    \emph{interpolates} colors and expects a \meta{list} of values in the range
    $[0,1000]$ where $0$ is the lowest element in the |colormap| and $1000$ is
    its highest element:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap name=hot,colorbar,
    cycle list={
        [colors of colormap={0,100,...,1000}]},
    %
    cycle from colormap manual style,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    In this case, we specified $11$ colors and have $11$ plots. Clearly,
    interpolated colors are of limited use and are only applicable for special
    use cases. Use only |cycle list|s of this sort if the |colormap| allows a
    suitable distinction of adjacent plot lines! Note that |colors of colormap|
    is quite similar to the related way to build colormaps based on existing
    colormaps as outlined in
    Section~\ref{sec:pgfplots:colormaps:based:on:others} on
    page~\pageref{sec:pgfplots:colormaps:based:on:others}.

    A related choice is \declareandlabel{indices of colormap}|=|\marg{list}. As
    above, it accepts an optional `|of|' clause of the form
    |indices of colormap=|\marg{list}| of |\meta{colormap name}. The main
    argument is a list of indices $0\le N_i < N$ where $N$ is the number colors
    in the colormap definition (compare the documentation of
    |index of colormap|). Indices which are out of range are clipped to the
    nearest index. For example, |viridis| comes with
    $\pgfplotscolormapsizeof{viridis}$~elements and we can write
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap name=viridis,colorbar,
    cycle list={
      [indices of colormap={0,4,8,12,17} of viridis]},
    %
    cycle from colormap manual style,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    Note that `| of viridis|' is actually redundant as |viridis| was already
    selected in this case.

    The complete syntax on how to customize |of colormap| is the same
    as the building blocks to define |colormap|s based on other
    |colormap|s as described in
    Section~\ref{sec:pgfplots:colormaps:based:on:others} on
    page~\pageref{sec:pgfplots:colormaps:based:on:others} -- with the
    difference that |cycle list={[of colormap]}| inserts the selected colors
    into the |cycle list| instead of a |colormap|.

    Note that all these special lists are valid arguments for
    |\pgfplotscreateplotcyclelist| and can also appear as sublists in
    |cycle multi list| and its variants.

    Since creating a |cycle list| from a |colormap| necessarily results in
    plots without markers and line style variations, it makes sense to combine
    the result with |cycle multiindex* list|, i.e.\@ to join two existing
    lists. The following example joins a pure color list with markers:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap name=hot,colorbar,
    cycle multiindex* list={
        [samples of colormap=11]\nextlist
        mark list\nextlist
    },
    cycle from colormap manual style,
]
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
    \addplot coordinates {(0,1) (0.5,1) (1,1)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    \noindent Please refer to the next subsection for details about
    |cycle multiindex* list|.

    Note that the preceding examples all use the following style.

    \begin{stylekey}{/pgfplots/cycle from colormap manual style}
        A style defined in this manual. It has the value
        %
\begin{codeexample}[code only]
\pgfplotsset{
    cycle from colormap manual style/.style={
        x=3cm,y=10pt,ytick=\empty,
        colorbar style={x=,y=,ytick=\empty},
        point meta min=0,point meta max=1,
        stack plots=y,
        y dir=reverse,colorbar style={y dir=reverse},
        every axis plot/.style={line width=2pt},
        legend entries={0,...,20},
        legend pos=outer north east,
    },
}
\end{codeexample}
    \end{stylekey}

}%

    \paragraph{Remark:}

    It is possible to call |\pgfplotsset{cycle list=|\marg{a list}|}| or
    |cycle list name| \emph{between} plots. Such a setting remains effective
    until the end of the current \TeX{} group (that means curly braces). Every
    |\addplot| command queries the |cycle list| using the plot index; it
    doesn't hurt if |cycle list|s have changed in the meantime.
\end{pgfplotskeylist}

\begin{pgfplotskey}{cycle list/.define=\marg{name}\marg{{list}}}
    A command which merely calls
    |\pgfplotscreateplotcyclelist|\marg{name}\marg{list} without actually
    selecting it as the current list.

    Note that \PGFPlots{} uses this to implement its |cycle list| key as
    follows:
    %
\begin{codeexample}[code only]
\pgfplotsset{
    cycle list/.style={%
        cycle list/.define={@internal@}{#1},%
        cycle list name={@internal@}%
    },
}
\end{codeexample}
    %
\end{pgfplotskey}


\subsubsection{Building Block to Combine Different Cycle Lists}

The following keys allow to combined different |cycle list|s in order to build
more complex ones.

\begin{pgfplotskey}{%
    cycle multi list=\meta{list 1}\texttt{\textbackslash nextlist}\meta{list 2}%
    \texttt{\textbackslash nextlist}$\ldots$
}
    This
    %\todosp{shouldn't the value list be surrounded by curly braces? (ff)}
    % -> not necessarily
    is one of two ways to employ more than one |cycle list| in order to
    determine the plot style (see also |cycle multiindex list| for the other
    one). This is probably best explained using an example:
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        cycle multi list={
            red,blue\nextlist
            solid,{dotted,mark options={solid}}\nextlist
            mark=*,mark=x,mark=o
        },
        samples=3,
        legend entries={0,...,20},
        legend pos=outer north east,
    ]
        \addplot {x};
        \addplot {x-1};
        \addplot {x-2};
        \addplot {x-3};
        \addplot {x-4};
        \addplot {x-5};
        \addplot {x-6};
        \addplot {x-7};
        \addplot {x-8};
        \addplot {x-9};
        \addplot {x-10};
        \addplot {x-11};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    \noindent The provided |cycle multi list| consists of three lists. The
    style for a single plot is made up using elements of each of the three
    lists: the first plot has style |red,solid,mark=*|, the second has
    |red,solid,mark=x|, the third has |red,solid,mark=o|. The fourth plot
    restarts the third list and uses the next one of list $2$: it has
    |red,dotted,mark options={solid},mark=*| and so on.

    The last list will always be advanced for a new plot. The list before the
    last (in our case the second list) will be advanced after the last one has
    been reset. In other words: |cycle multi list| allows a composition of
    different |cycle list| in a lexicographical way.\footnote{For those who
    prefer formulas: The plot with index $0 \le i < N$ will use cycle list
    offsets $i_0,i_1,\dotsc,i_k$, $0 \le i_m < N_m$ where $k$ is the number of
    arguments provided to \texttt{cycle multi list} and $N_m$ is the number of
    elements in the $m$th cycle list. The offsets $i_m$ are computed in a loop
    {\ttfamily \{ int tmp=i;  for( int m=k-1; m>=0; m=m-1 ) \{ i\_m =
    tmp\%N\_m; tmp = tmp/N\_m; \}\}}.}

    The argument for |cycle multi list| is a sequence of arguments as they
    would have been provided for |cycle list|, separated by
    \declareandlabel{\nextlist}. In addition to providing a new cycle list, the
    \meta{list $i$} elements can also denote |cycle list name| values
    (including the special |auto| cycle list which is the most recently
    assigned |cycle list| or |cycle list name|). The final |\nextlist| is
    optional.

    The list in our example above could have been written as
    %
\begin{codeexample}[code only]
\begin{axis}[
    cycle multi list={
        red\\blue\\\nextlist
        solid\\dotted,mark options={solid}\\\nextlist
        mark=*\\mark=x\\mark=o\\
    },
]
\end{codeexample}
    %
    \noindent as well (note the terminating |\\| commands!).

\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title={Cycle color between successive plots, then marks},
        cycle multi list={
            mark list\nextlist
            blue,red
        },
        samples=3,
        legend entries={0,...,20},
        legend pos=outer north east,
    ]
        \addplot {x};
        \addplot {x-1};
        \addplot {x-2};
        \addplot {x-3};
        \addplot {x-4};
        \addplot {x-5};
        \addplot {x-6};
        \addplot {x-7};
        \addplot {x-8};
        \addplot {x-9};
        \addplot {x-10};
        \addplot {x-11};
    \end{axis}
\end{tikzpicture}
\end{codeexample}


    \paragraph{Using Sublists}

    The \meta{list $i$} entry can also contain just the first $n$ elements of
    an already known cycle list name using the syntax
    |[|\meta{number}| of]|\meta{cycle list name}. For example |[2 of]mark list|
    will use the first $2$ elements of |mark list|:
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title={Cycle 2 marks between successive plots, then colors},
        cycle multi list={
            color list\nextlist
            [2 of]mark list
        },
        samples=3,
        legend entries={0,...,20},
        legend pos=outer north east,
    ]
        \addplot {x};
        \addplot {x-1};
        \addplot {x-2};
        \addplot {x-3};
        \addplot {x-4};
        \addplot {x-5};
        \addplot {x-6};
        \addplot {x-7};
        \addplot {x-8};
        \addplot {x-9};
        \addplot {x-10};
        \addplot {x-11};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
    %
\end{pgfplotskey}

\begin{pgfplotskey}{%
    cycle multiindex list=\meta{list 1}\texttt{\textbackslash nextlist}\meta{list 2}%
    \texttt{\textbackslash nextlist}$\ldots$
}
    This is one of two ways to employ more than one |cycle list| in order to
    determine the plot style (see also |cycle multi list| for the other one).
    The difference between the two choices is how the list index is mapped into
    the sub lists. Let us start with our example:
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        cycle multiindex list={
            red,blue,teal\nextlist
            solid\\dotted,mark options={solid}\\only marks\\\nextlist
            mark=*,mark=x,mark=oplus\nextlist
        },
        samples=3,
        legend entries={0,...,20},
        legend pos=outer north east,
    ]
        \addplot {x};
        \addplot {x-1};
        \addplot {x-2};
        \addplot {x-3};
        \addplot {x-4};
        \addplot {x-5};
        \addplot {x-6};
        \addplot {x-7};
        \addplot {x-8};
        \addplot {x-9};
        \addplot {x-10};
        \addplot {x-11};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    \noindent The provided |cycle multiindex list| consists of three lists. The
    style for a single plot is made up using elements of each of the three
    lists: the first plot has style |red,solid,mark=*|, the second has
    |blue,dotted,mark options={solid},mark=x|, the third has
    |teal,only marks,oplus|. The fourth plot restarts all lists and uses the
    same as the first plot, i.e.\@ |red,solid,mark=*|.

    Note that the second list uses the list-separator `|\\|' which requires a
    final terminator as defined for |cycle list|.

    Thus, this style uses \emph{the same} index into every list (a ``multi
    index''). Consequently, it has considerably less different choices than
    |cycle multi list| (which results in all possible variations), but its
    combination method addresses different use cases.

    The argument for |cycle multiindex list| has the very same format as the
    one for |cycle multi list|, including the special |[2 of]mark list| syntax
    and providing other cycle lists by name:
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title={Same index of each input list},
        cycle multiindex list={
            [3 of]mark list\nextlist
            blue,red\nextlist
            linestyles\nextlist
        },
        samples=3,
        legend entries={0,...,20},
        legend pos=outer north east,
    ]
        \addplot {x};
        \addplot {x-1};
        \addplot {x-2};
        \addplot {x-3};
        \addplot {x-4};
        \addplot {x-5};
        \addplot {x-6};
        \addplot {x-7};
        \addplot {x-8};
        \addplot {x-9};
        \addplot {x-10};
        \addplot {x-11};
    \end{axis}
\end{tikzpicture}
\end{codeexample}

    Note that |cycle multiindex list| accepts lists of different sizes. The
    size of a |cycle multiindex list| is the size of the \emph{largest} input
    list, all smaller input lists are padded with empty option lists. That is
    why the previous example uses the color |black| for every third plot: there
    is no color in the second list, and omitting the color results in |black|.
    As soon as the last item of the largest sublist has been used, the list is
    restarted.
\end{pgfplotskey}

\begin{pgfplotskey}{%
    cycle multiindex* list=\meta{list 1}\texttt{\textbackslash nextlist}\meta{list 2}%
    \texttt{\textbackslash nextlist}$\ldots$
}
    A variant of |cycle multiindex list| which behaves in the same way --
    except for sublists of different sizes.

    As documented above, the unstarred version |cycle multiindex list| pads
    missing entries with \emph{empty} options lists until all list elements
    have the same size.

    The starred key |cycle multiindex* list| restarts sublists independently
    whenever they reach their end:
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title={Same index of each input list, lists restarted},
        cycle multiindex* list={
            [3 of]mark list\nextlist
            blue,red\nextlist
            linestyles\nextlist
        },
        samples=3,
        legend entries={0,...,20},
        legend pos=outer north east,
    ]
        \addplot {x};
        \addplot {x-1};
        \addplot {x-2};
        \addplot {x-3};
        \addplot {x-4};
        \addplot {x-5};
        \addplot {x-6};
        \addplot {x-7};
        \addplot {x-8};
        \addplot {x-9};
        \addplot {x-10};
        \addplot {x-11};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    This is the very same example as documented for the unstarred variant
    |cycle multiindex list|. However, the second sublist has fewer elements --
    and while the unstarred variant resulted in |black|, the starred variant
    restarts the second sublist as soon as its two existing colors are
    consumed.

    This style allows to concatenate lists in complex ways:
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title={Same index of each input list},
        cycle multiindex* list={
            red,blue,teal,brown\nextlist
            mark=*,mark=square*,mark=triangle*\nextlist
            dashed,every mark/.append style={
                solid,draw=.!50!black,fill=.,}\\
            \nextlist
        },
        samples=3,
        legend entries={0,...,20},
        legend pos=outer north east,
    ]
        \addplot {x};
        \addplot {x-1};
        \addplot {x-2};
        \addplot {x-3};
        \addplot {x-4};
        \addplot {x-5};
        \addplot {x-6};
        \addplot {x-7};
        \addplot {x-8};
        \addplot {x-9};
        \addplot {x-10};
        \addplot {x-11};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    We see that the four different colors appear periodically as expected. We
    also see the three different markers with their own period (which restarts
    every fourth plot as expected). But the third sublist contains just one
    element as we can see by its separator character `|\\|' which appears just
    once at the end of the list! Consequently, this list is restarted for
    \emph{every} plot such that every plot receives its arguments.
\end{pgfplotskey}


\subsection{Axis Background}

\begin{pgfplotskey}{axis background (initially empty)}
    This is a style to configure the appearance of the axis as such. It can be
    defined and/or changed using the |axis background/.style=|\marg{options}
    method. A background path will be generated with \meta{options}, which may
    contain fill colors or shadings.
    %
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    axis background/.style={fill=blue!10},
]
    \addplot3 [
        surf,
        y domain=0:1,
    ]
        {sin(deg(x)) * y*(1-y)};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    Please note that legends are filled with white in the default
    configuration.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{semilogyaxis}[
    axis background/.style={
        shade,top color=gray,bottom color=white,
    },
    legend style={fill=white},
]
    \addplot {exp(-x)};
    \addplot {exp(-4*x)};

    \legend{$e^{-x}$,$e^{-4x}$}
\end{semilogyaxis}
\end{tikzpicture}
\end{codeexample}
    %
    Details about |fill| and |shade| can be found in the \Tikz{} manual,
    \cite{tikz}.
\end{pgfplotskey}


\section{Providing Color Data -- Point Meta}
\label{pgfplots:point:meta}

\PGFPlots{} provides features which modify plots depending on a special
coordinate, the ``point meta data''. For example, scatter plots may vary marker
colors, size or appearance depending on this special data. Surface and mesh
plots are another example: here, the color of a surface patch (or mesh part)
depends on ``point meta''. The ``meta data'' of a node is not the position
(which is given as $(x,y)$ or $(x,y,z)$). It is ``some information'' about that
node; you could say: it is a specific property of the node. This is commonly
called ``meta data''.


\subsection{Point Meta Overview}

In \PGFPlots{}, every node has its coordinate \emph{and} its meta data. Thus,
two-dimensional plots have three values: $x$, $y$, and the |point meta| data.
Three-dimensional plots have four values for each coordinate: $x$, $y$, $z$,
and the |point meta|.

In many cases, |point meta| is interpreted to be color data. To be more
precise: it is interpreted to be \emph{scalar} color data which is mapped into
the |colormap| (more about this approach in the next paragraphs). However,
|point meta| can be anything. Often, it is a single number as in the case of
color data. That number is mapped linearly to the interval $[0,1000]$ such that
$0$ corresponds to the smallest encountered value and $1000$ corresponds to the
largest encountered scalar value. The mapped value is available as
|\pgfplotspointmetatransformed|. This special value allows to define some
property of the plot: it can be the color (together with |colormap|). It can
also be the |line width| in a |mesh| plot (more precisely: the |line width|
could be defined to depend on the transformed meta data). An example for this
approach is on page~\pageref{pgfplots:example:pointmeta:quiver} where a
|quiver| plot's arrow line with depends on |\pgfplotspointmetatransformed|. The
value can also be used to define |mark size| as in the example for
|scatter/@pre marker code| on
page~\pageref{pgfplots:example:pointmeta:scatter}. However, |point meta| data
does not necessarily need to be a number. It can be a text label (any text that
you like). This is used by |nodes near coords|, for example. It could also
contain a tuple like RGB color information (compare
|mesh/color input=explicit|). Thus, |point meta| is really some abstract
information about individual coordinates.

Note that there is only \emph{one} |point meta| per point. See the key
|visualization depends on| if you need more than one meta data value per
coordinate.

The common idea is to tell \PGFPlots{} how to get the meta data. It is not
necessary to provide data explicitly -- in many cases, the data which is used
to color |surf|ace patches or |mark|er colors is the plot's $y$ or $z$
coordinate. The method used to tell \PGFPlots{} where to find ``point meta
data'' is the |point meta| key.

The most common use case of |point meta| is color information: if the point
meta data is in the interval $[m_{\min},m_{\max}]$, the point meta coordinate
for the smallest encountered value $m = m_{\min}$ will get the lowest color
provided by the |colormap| while the largest encountered value $m=m_{\max}$
will get the highest color provided by the |colormap|. As already mentioned,
this is accomplished using |\pgfplotspointmetatransformed| $\in [0,1000]$ (per
convention). Any coordinate between the smallest and largest values will be
mapped linearly: for example, the mean $m = 1/2 (m_{\max} + m_{\min})$ will get
the middle color of the color map (it will have |\pgfplotspointmetatransformed|
$=500$). This is why ``point meta'' is sometimes called ``color data'' in this
manual.

\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[colorbar]
        \addplot [mesh,point meta=y,thick] {x^2};
    \end{axis}
\end{tikzpicture}
\end{codeexample}


\subsection{User Input Format for Point Meta}

\begin{pgfplotskey}{point meta=\mchoice{%
        none,
        \meta{expression},
        x,y,z,f(x),
        explicit,explicit symbolic%
    } (initially none)%
}
\label{pgfplots:pointmeta}
    The |point meta| key tells \PGFPlots{} where to get the special point meta
    data. Please note that |point meta| and |scatter src| is actually the same
    -- |scatter src| is an alias for |point meta|. Thus, the summary provided
    for |scatter src| on page~\pageref{pgfplots:scatter:src} covers the same
    topics. However, the main reference for |point meta| is here.
    %
    \begin{description}
        \item[\declaretext{none}] The initial choice |none| disables point
            meta data, resulting in no computational work. Any other choice
            will activate the computation of upper and lower ranges for point
            meta data, i.e.\@ the computation of $[m_{\min},m_{\max}]$.
        \item[\declaretext{x}] The choice |x| uses the already available $x$
            coordinates as point meta data. This does always refer to the
            \emph{final} $x$-coordinates after any user transformations,
            logarithms, stacked plot computations, etc.\@ have been applied.
            Consider using |rawx| if you need the unprocessed coordinate value
            here.
        \item[\declaretext{y}]
        \item[\declaretext{z}] The choices |y| and |z| are similar: they use
            the $y$- or $z$-coordinates respectively as point meta data.
            Consequently, these three choices do \emph{not} need any extra
            data. As for |x|, there are math constants |rawy| and |rawz| which
            yield the unprocessed $y$ and $z$ value, respectively.
        \item[\declaretext{f(x)}] This will use the last available
            coordinate, in other words: it is the same as |y| for two
            dimensional plots and |z| for three dimensional ones.
        \item[\declaretext{explicit}] This choice tells \PGFPlots{} to expect
            \emph{numerical} point meta data which is provided explicitly in
            the coordinate input streams. This data will be transformed
            linearly into the current color map as it has been motivated
            above.

            How point meta data is provided for |\addplot coordinates|,
            |\addplot table| and the other input methods is described in all detail
            in Section~\ref{pgfplots:providing:input} -- but we provide small
            examples here to summarize the possibilities:
            %
\begin{codeexample}[code only]
% for 'coordinates':
% provide color data explicitly using [<data>]
% behind coordinates:
\addplot+ [point meta=explicit]
    coordinates {
        (0,0) [1.0e10]
        (1,2) [1.1e10]
        (2,3) [1.2e10]
        (3,4) [1.3e10]
        % ...
    };
\end{codeexample}

\begin{codeexample}[code only]
% for 'table':
% Assumes a datafile.dat like
% xcolname  ycolname    colordata
% 0         0           0.001
% 1         2           0.3
% 2         2.1         0.4
% 3         3           0.5
% ...
% the file may have more columns.
\addplot+ [point meta=explicit]
    table [x=xcolname,y=ycolname,meta=colordata]
        {datafile.dat};
% or, equivalently (perhaps a little bit slower):
\addplot+ [point meta=\thisrow{colordata}]
    table [x=xcolname,y=ycolname]
        {datafile.dat};
\end{codeexample}

\begin{codeexample}[code only]
% for 'file':
% Assumes a datafile.dat like
% 0         0           0.001
% 1         2           0.3
% 2         2.1         0.4
% 3         3           0.5
% ...
% the first three columns will be used here as x,y and meta,
% resp.
\addplot+ [point meta=explicit]
    file {datafile.dat};
\end{codeexample}

\begin{codeexample}[code only]
% 'table' using expressions which may depend on all
% columns:
% Assumes a datafile.dat like
% xcolname  ycolname    anything    othercol
% 0         0           4           15
% 1         2           5           20
% 2         2.1         8           30
% 3         3           42          40
% ...
% the file may have more columns.
\addplot+ [point meta={0.5*(\thisrow{anything} + sqrt(\thisrow{othercol}))}]
    table [x=xcolname,y=ycolname]
        {datafile.dat};
\end{codeexample}
            %
            Thus, there are several methods to provide point meta (color
            data). The key for the choice |explicit| is that some data is
            provided explicitly -- although |point meta| does not know how.
            The data is expected to be of numerical type and is mapped
            linearly into the range $[0,1000]$ (maybe for use in the current
            color map).
        \item[\declaretext{explicit symbolic}] The choice |explicit symbolic|
            is very similar to |explicit| in that it expects extra data by
            the coordinate input routines. However, |explicit symbolic| does
            not necessarily expect numerical data: you can provide any sort
            of symbols. One might provide a set of styles, one for each class
            in a scatter plot. This is implemented using |scatter/classes|,
            see page~\pageref{pgfplots:scatterclasses}. Input data is
            provided in the same fashion as mentioned above for the choice
            |explicit|.

            This choice is usedful for |nodes near coords| with textual
            labels (see
            page~\pageref{pgfplots:example:pointmeta:nodesnearcoords}) and
            for |surf|ace plots with explicit color (see
            |mesh/color input=explicit| for details).
        \item[\normalfont\declare{\meta{expression}}] This choice allows to
            compute point meta data using a mathematical expression. The
            \meta{expression} may depend on |x|, |y|, |z| which yield the
            current $x$-, $y$- or $z$-coordinate, respectively. The coordinates
            are completely processed (transformations, logs) as mentioned above
            for the choice |x|. Furthermore, the \meta{expression} may depend
            on commands which are valid during |\addplot| like |\plotnum| or
            |\coordindex| (see Section~\ref{pgfplots:misc} for details). If
            coordinates are provided using |\addplot table|, the macro
            |\thisrow|\marg{colname} is particularly useful as it allows to
            access the value of the provided \meta{colname} of the ``current''
            row. Computations are performed using the floating point unit of
            \PGF{}, and all supported arithmetical operations can be used.

            In essence, the \meta{expression} may depend on everything which is
            known to all |\addplot| commands: the $x$, $y$ and (if any) $z$
            coordinates. In addition, it may depend upon |rawx|, |rawy| or
            |rawz|. These three expressions yield the unprocessed $x$, $y$ or
            $z$ value as it has been found in the input stream (no logs, no
            user transformations).%
            \footnote{%
                In rare circumstances, it might be interesting to apply a
                math expression to another source of point meta (one of the
                other choices). To this end, the \meta{expression} is checked
                after the other possible choices have already been evaluated.
                In other words, the statement \texttt{point meta=explicit,
                point meta=meta*meta+3} will evaluate the expression with
                |meta| set to whatever data has been provided explicitly.%
            }
            If used together with |\addplot table|, you may also access other
            table columns (for example with |\thisrow|\marg{colname}).
        \item[\normalfont\declaretext{TeX code}\texttt{=}\meta{code}] A
            rather low level choice which allows to provide \TeX{}
            \meta{code} to compute a numerical value. The \meta{code} should
            define the macro |\pgfplotspointmeta|. It is evaluated in a
            locally scoped environment (it's local variables are freed
            afterwards). It may depend on the same values as described for
            \meta{expression} above, especially on |\thisrow|\marg{colname}
            for table input.

            Note that the math parser will be configured to use the |fpu| at
            this time, so |\pgfmathparse| yields floats.

            Note that you need an extra pair of braces to provide this key,
            i.e.\@

            |point meta={TeX code=|\marg{code}|}|.

        \item[\normalfont\declaretext{TeX code
            symbolic}\texttt{=}\meta{code}] Just as |TeX code|, you can
            provide \meta{code} which defines the macro |\pgfplotspointmeta|,
            but the result is not interpreted as a number. It is like the
            |explicit symbolic| choice.

            Note that you need an extra pair of braces to provide this key,
            i.e.\@

            |point meta={TeX code symbolic=|\marg{code}|}|.
        \item[\normalfont\declaretext{symbolic}\texttt{=}\meta{symbol}] A
            choice which accepts some arbitrary \meta{symbol} which is used
            for every coordinate. As |explicit symbolic| and
            |TeX code symbolic|, this choice yields symbolic representations,
            i.e.\@ it is kept as is without mapping the result.

            The difference to |explicit symbolic| is that \meta{symbol} is a
            common symbol for all points whereas |explicit symbolic| expects
            the input data stream (like a table) to provide individual
            symbols.

            The different to |TeX code symbolic| is marginal: |symbolic| is
            actually the same as

            |point meta/TeX code symbolic={\def\pgfplotspointmeta|\marg{symbol}|}|.

            A use case for |symbolic| is
            |mesh/color input=explicit mathparse|, see the documentation
            there-in.

            Note that you need an extra pair of braces to provide this key,
            i.e.\@

            |point meta={symbolic=|\marg{symbol}|}|.
    \end{description}

    As already mentioned, a main application of point meta data is to determine
    (marker/face/edge) colors using a linear map into the range $[0,1000]$
    (maybe for use in the current color map). This map works as follows: it is
    a function
        \[ \phi\colon [m_{\min},m_{\max}] \to [0,1000] \]
    with
        \[ \phi(m) = \frac{m - m_{\min}} {1000} \]
    such that $\phi(m_{\min}) = 0$ and $\phi(m_{\max})=1000$. The value $1000$
    is -- per convention -- the upper limit of all color maps. Now, if a
    coordinate (or edge/face) has the point meta data $m$, its color will be
    determined using $\phi(m)$: it is the color at $\phi(m)$\textperthousand{}
    of the current color map.

    This transformation depends on the interval $[m_{\min},m_{\max}]$ which, in
    turn, can be modified using the keys |point meta rel|, |point meta min| and
    |point meta max| described below.

    The untransformed point meta data is available in the macro
    \declareandlabel{\pgfplotspointmeta} (only in the correct context, for
    example the scatter plot styles or the |scatter/@pre marker code|
    interface). This macro contains a low level floating point number (unless
    it is non-parsed string data). The transformed data will be available in
    the macro \declareandlabel{\pgfplotspointmetatransformed} and is in fixed
    point representation. It is expected to be in the range $[0,1000]$.

\end{pgfplotskey}

\begin{pgfplotskey}{set point meta if empty=\marg{point meta source}}
    Sets |point meta=|\meta{point meta source}, but only if |point meta=none|
    currently. This is used for |scatter|, |mesh| and |surf| with
    |set point meta if empty=f(x)|.
\end{pgfplotskey}


\subsection{Mapping Point Meta and Color Maps}

As already explained in the documentation for |point meta|, one application for
point meta data is to determine colors using the current color map and a linear
map from point meta data into the current color map. This subsection shows keys
to control this mapping.

The plot handlers |surf|, |mesh|, |patch|, |scatter|, |contour prepared|, and
some related ones all make use of mapped colors. To this end, the value
provided by |point meta| is processed as follows:
%
\begin{itemize}
    \item First, all encountered values are collected (during |\addplot|) and
        the largest and smallest value, $m_{\max}$ and $m_{\min}$, are
        computed. The value is stored in |\pgfplotspointmeta|.
    \item Second, every encountered value $m$ is mapped to $[0,1000]$ using a
        linear map: $m_{\min} \to 0$; $m_{\max}\to 1000$, and all values
        in-between are mapped linearly. This value is stored (and available)
        in the \TeX{} macro |\pgfplotspointmetatransformed| (but not before
        |\end{axis}|).
    \item Finally, the mapped value |\pgfplotspointmetatransformed| is mapped
        into the current |colormap|. The resulting color is called
        \declareandlabel{mapped color}.
\end{itemize}
%
The plot handlers, in turn, use |mapped color| in order to render their colors
(often combined with color mixins like |mapped color!80!black|).

\begin{pgfplotskey}{point meta rel=\mchoice{axis wide,per plot} (initially axis wide)}
    The key |point meta rel| configures whether the interval of all point meta
    coordinates, $[m_{\min},m_{\max}]$ is computed as maximum over all plots in
    the complete axis (the choice \declaretext{axis wide}) or only for one
    particular plot (the choice \declaretext{per plot}).

\message{Overfull hbox is ok.}%
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title=Axis wide color mapping,
        colorbar,
        samples=50,point meta rel=axis wide,
        point meta=y,
    ]
        \addplot [mesh,thick] {sin(deg(x))};
        \addplot [mesh,thick] {3*tanh(x)};
    \end{axis}
\end{tikzpicture}
~
\begin{tikzpicture}
    \begin{axis}[
        title=Per Plot color mapping,
        colorbar,
        samples=50,
        point meta rel=per plot,
        point meta=y,
    ]
        \addplot [mesh,thick] {sin(deg(x))};
        \addplot [mesh,thick] {3*tanh(x)};
   \end{axis}
\end{tikzpicture}
\end{codeexample}

    Note that a |colorbar| will still use the |axis wide| point meta limits.
    Consider the |colorbar source| key if you want the color data limits of a
    \emph{particular} plot for your color bar. The |point meta rel| key
    configures how point meta maps to colors in the |colormap|.
\end{pgfplotskey}

\begin{pgfplotskeylist}{point meta min=\marg{number},point meta max=\marg{number}}
    These keys allow to define the range required for the linear map of point
    meta data into the range $[0,1000]$ (for example, for current maps)
    explicitly. This is necessary if the same mapping shall be used for more
    than one axis.


    \paragraph{Remarks about special cases:}

    \begin{itemize}
        \item It is possible to provide limits partially; in this case, only
            the missing limit will be computed.
        \item If point meta data falls outside of these limits, the linear
            transformation is still well defined which is acceptable (unless
            the interval is of zero length). However, color data can't be
            outside of these limits, so color bars perform a truncation.
        \item This key can be provided for single plots as well as for the
            complete axis (or for both).
        \item If meta limits are provided for a single plot, these limits may
            also contribute to the axis wide meta interval.
    \end{itemize}
\end{pgfplotskeylist}

\begin{pgfplotskey}{colormap access=\mchoice{%
        map,
        direct,
        const,\\
        piecewise constant,
        piecewise const,
        piecewise linear%
    } (initially map)%
}
    This key configures how point meta data is used to determine colors from a
    color map.


    \subsubsection{Mapping Point Meta using Piecewise Constant Interpolation}

    The initial configuration \declaretext{map} performs the linear mapping
    operation explained above in all detail.


    \subsubsection{Using Colormaps as Indexed Color Space (Palette)}

    The choice \declaretext{direct} does not perform any transformation; it
    interprets the value of |point meta| as integer indices into the current
    color map. If a number is no integer, it will be truncated by throwing away
    any fraction parts of the number. Consequently, it is quite similar to
    |index of colormap|.\index{index of colormap}

\def\showcolorandname#1{%
    \showcolor{#1}~\pgfmanualpdfref{#1}{\texttt{#1}}%
}%
\def\showcolor#1{%
    \tikz \draw[black,fill={#1}] (0,0) rectangle (1em,0.6em);%
}%
%
    Suppose we have the color definitions
    %
    \showcolorandname{RdPu-K},
    \showcolorandname{RdPu-I},
    \showcolorandname{RdPu-G},
    \showcolorandname{RdPu-E}, and
    \showcolorandname{RdPu-B}
    %
    (which are actually taken from |\usetikzlibrary{colorbrewer}|).

    We will use these colors in order to define a |colormap|:
    %
\begin{codeexample}[]
% requires \usetikzlibrary{colorbrewer}
\begin{tikzpicture}
\begin{axis}[
    colormap={brewer}{
        color=(RdPu-B) color=(RdPu-E)
        color=(RdPu-G) color=(RdPu-I)
        color=(RdPu-K)
    },
    enlargelimits=false,
    colorbar as palette,
]
    \addplot [
        matrix plot,
        nodes near coords,mark=*,
        point meta=explicit,
        colormap access=direct,
    ] coordinates {
        (0,0) [0] (1,0) [1] (2,0) [2] (3,0) [NaN]

        (0,1) [3] (1,1) [4] (2,1) [5] (3,1) [99]

        (0,2) [3.5] (1,2) [-1] (2,2) [2.99] (3,2) [3]
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    The example has a $3\times 4$ matrix, each with explicitly provided values
    of |point meta|. The first point has a |point meta| value of~$0$ and uses
    the first color of the |colormap| (|RdPu-B|, \showcolor{RdPu-B}). The
    second point has value~$1$ and uses the second color, |RdPu-E|
    \showcolor{RdPu-E}, and so on. Note that |NaN| is interpreted as `hole' in
    the matrix and is left empty (you see the background color here). Note
    furthermore that coordinate |(1,2) [-1]| is mapped to the first color since
    values outside of the allowed range are automatically clipped to the next
    correct color. The same holds for the point with |[99]|: it is mapped to
    the last available color~\showcolor{RdPu-K}. Finally, the point with
    |[2.99]| is mapped to index $2$~(\showcolor{RdPu-G}) since
    |colormap access=direct| truncates to the next integer index.

    \begin{pgfplotskey}{colorbar as palette}
        The example above makes use of |colorbar as palette|, a dedicated style
        useful for such palette-type applications.

        It is defined as
        %
\begin{codeexample}[code only]
\pgfplotsset{
    colorbar as palette/.style={
        colorbar sampled={
            surf,
            colormap access=direct,
            shader=flat corner,
            samples=\pgfplotscolormapsizeof
            {\pgfkeysvalueof{/pgfplots/colormap name}}+1,
        },
        colorbar style={
            point meta min=0,
            point meta max=\pgfplotscolormapsizeof
            {\pgfkeysvalueof{/pgfplots/colormap name}},
        },
    },
}
\end{codeexample}
        %
        The idea is to show only the colors of the ``palette'', i.e.\@ without
        interpolating values of the |colormap|. Furthermore, it is supposed to
        show all available colors.

        See also the closely related (but more general) |colorbar as legend|.
\end{pgfplotskey}

    Note that |colormap access=direct| changes the way how |point meta| is
    translated to colors. However, it does \emph{not affect} |shader|. In other
    words, it is perfectly sane to use |shader=interp| or |shader=flat mean|.
    This, however, will interpolate the colors resulting from
    |colormap access=direct|! Our example above uses |shader=flat corner| which
    results in no color interpolation at all.

    The choice |colormap access=direct| is actually like a color palette for
    images with indexed colorspaces: suppose we use the famous ``Lena''
    image~\cite{lena}, downsample it to $128\times 128$, and export it to
    coordinates of the form
    %
\begin{codeexample}[code only]
1 1 194
1 2 194
1 3 170
1 4 193
1 5 188
1 6 188
...
\end{codeexample}
    %
    with an indexed colorspace. Furthermore, we import its color palette as
    \PGFPlots{} |colormap|. To this end, a small Matlab script serves as
    utility to convert a |tiff| image to coordinates:\footnote{Also see
    Section~\ref{sec:pgfplots:import:matlab}, ``Importing Mesh Data From Matlab
    To PGFPlots'' on page~\pageref{sec:pgfplots:import:matlab}}
    %
\begin{codeexample}[code only]
[Z,cm] = imread('4.2.04_128.tiff');
[X,Y]=meshgrid(1:size(Z,1), 1:size(Z,2));
data = [ X(:) Y(:) Z(:) ];
fid = fopen('lena.dat', 'w');
fprintf(fid, "%d %d %d\n", data');
fclose(fid);

fid = fopen('lena_cm.tex', 'w');
fprintf(fid, "\\pgfplotsset{colormap={lena palette}{\n");
fprintf(fid, "rgb=(%f,%f,%f)\n", cm');
fprintf(fid, "}}\n");
fclose(fid);
\end{codeexample}
    %
    This allows us to import the graphics into \PGFPlots{} as |matrix plot|:
    %
\tikzset{external/figure name/.add={}{lena_}}%
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
    % load and activate the CM:
    \input{lena_cm.tex}
\begin{axis}[view={0}{90},axis equal]
    \addplot3 [
        matrix plot,
        colormap access=direct,
        mesh/rows=128,
        mesh/ordering=colwise,
    ] table {lena.dat};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    The files |lena_cm.tex| and |lena.dat| are shipped with \PGFPlots{} and can
    be downloaded from CTAN. The keys to decode the table data into a |mesh|
    are specific to the Matlab export format of our script.

    Note that rendering images from coordinates is considerably less efficient
    than |\includegraphics| in terms of
    %
    \begin{itemize}
        \item computational time required by \PGFPlots{},
        \item space consumption in the resulting |pdf| document,
        \item and time to render the resulting |pdf| in the viewer(s).
    \end{itemize}
    %
    Depending on the use case, \verbpdfref{\addplot graphics} may help to
    reduce typesetting times.


    \paragraph{Some more details:}

    \begin{itemize}
        \item If there are $m$ colors in the color map and the color data
            falls outside of $[0,m-1]$, it will be pruned to either the first
            or the last color.
        \item If color data is a real number, it will be truncated to the
            next smaller integer.
        \item If |colormap access=direct| is combined with a
            |shader|$\neq$|flat corner|, color interpolation takes place.
            However, the color interpolation is not carried out in terms of
            the scalar |point meta| (as would have been done for
            |colormap access=map|). Instead, it is carried out on the
            \emph{resulting} colors in their own colorspace.
        \item Note that |patch refines| or |patch to triangles| is
            unsupported in this context (at the time of this writing, it will
            interpolate the color indices, resulting in badly defined
            behavior).
    \end{itemize}

    See also the related keys |color of colormap| and |index of colormap|.

    The choice |colormap access=|\declaretext{piecewise linear} is an alias for
    |colormap access=map|. It is related to |color of colormap|.
    \index{color of colormap}


    \subsubsection{Mapping Point Meta using Piecewise Constant Interpolation}

    \paragraph{Beware: Viewer Limitations}

    The following paragraph makes uses of \textsc{pdf} features which are
    unsupported by some free viewers (including |pdf.js| and |evince|). Please
    resort to a suitable viewer if you see unexpected results.

    The choice |colormap access=|\declaretext{piecewise constant} is very
    similar to |colormap access=map|: it accepts the same |point meta| values
    as input, maps them linearly into $[0,1000]$ and uses the first color of
    the |colormap| if the value of |point meta| is |point meta min| and the
    last color of the |colormap| if the value of |point meta| is
    |point meta max|. However, values of |point meta| which fall \emph{between}
    two |colormap| entries are interpolated using \emph{piecewise constant}
    interpolation, i.e.\@ just like |const plot|: the interpolated color
    resembles the value of the \emph{first} color of the interval. As a
    consequence, the result contains at most as many colors as the |colormap|
    provides:
    %
\begin{codeexample}[]
% requires \usepgfplotslibrary{colorbrewer}
\begin{tikzpicture}
\begin{axis}[
    colormap access=piecewise constant,
    colormap/RdPu-6,
    colorbar horizontal,
]
    \addplot3 [
        surf,
    ] {x*y};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    The choice |colormap access=piecewise constant| is compatible with all
    available |shader|s, but its best results are possible using
    |shader=interp| as this will avoid rectangular artifacts at mesh
    boundaries.
    %
\begin{codeexample}[]
% requires \usepgfplotslibrary{colorbrewer}
\begin{tikzpicture}
\begin{axis}[
    colormap access=piecewise constant,
    colormap/RdPu-6,
    colorbar horizontal,
]
    \addplot3 [
        surf,
        shader=interp,
    ] {x*y};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    The choice |colormap access=piecewise constant| requires |colormap|s with a
    suitable number of colors. This is quite different to |colormap access=map|
    (or |piecewise linear|) where the actual number of colors in the |colormap|
    cannot be seen in the resulting plot. In order to get the desired effects,
    one may need the same |colormap| with a different number of samples. To
    this end, one can make use of the special |colormap| syntax which is based
    on |samples of colormap| and its variants:

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    colormap access=piecewise constant,
    colormap={my sampled version of viridis}{
        samples of colormap=(10 of viridis)
    },
    colorbar horizontal,
]
    \addplot3 [
        surf,
        shader=interp,
    ] {x*y};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    The example takes the existing |colormap name=viridis| and chooses $10$
    samples of it. The result is called |my sampled version of viridis| and is
    used as ``current colormap''. Details about this process can be read in
    Section~\ref{sec:pgfplots:colormaps:based:on:others} on
    page~\pageref{sec:pgfplots:colormaps:based:on:others}.


    \paragraph{See also}

    the plot handler |contour filled| which is based on such a visualization
    scheme.

    The strategy which determines colors in this context is also available as
    |const color of colormap|.\index{const color of colormap}

    The choices \declareandlabel{piecewise const} and \declaretext{const} are
    aliases for |piecewise constant|.
\end{pgfplotskey}
